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内 容 拓 要 


本 书 是 一 本 经 典 而 实用 的 畅销 Spring 学 习 指 两 。 


第 5 版 涵盖 了 Spring 5.0 和 Spring Boot 2.0 里 程 碑 式 的 更 新 。 全 书 分 为 
5 个 部 分 ， 共 19 章 。 第 1 部 分 〈 第 1 一 5 章 ) 涵盖 了 构建 Spring 应 用 的 基础 
话题 。 第 2 部 分 〈 第 6 一 9 章 ) 讨论 如 何 将 Spring 应 用 与 其 他 应 用 进行 集 
成 。 第 3 部 分 《第 10 一 12 章 ) 探讨 Spring 对 反应 式 编程 提供 的 全 新 支持 。 
第 4 部 分 《第 13 一 15 章 ) 拆 分 单 体 应 用 和 模 型， 介绍 Spring Cloud 和 微服 务 
开发 。 第 5 部 分 〈 第 16 一 19 章 ) 讨论 如 何 为 应 用 投入 生产 环境 做 准备 以 
及 如 何 进行 部 署 。 


本 书 既 适合 刚 开 始 学 习 Spring Boot 和 Spring 框架 的 Java 开 发 人 员 快 
2 


速 上 手 ， 也 运 合 经 验 丰 军 的 Spring 开发 人 员 学 习 Spring 的 新 特性 ， 尤 其 
适用 于 企业 级 Java 开 发 人 员 。 


译 痢 订 


不 知 不 觉 间 ， 已 经 参与 了 3 个 版 本 的 《Spring 实战 》 翻 译 。2007 年 春 
天 ， 当 时 J2EE Without EJB 的 风 请 刚刚 兴起 ， 还 在 读 研 的 我 在 天 津 大 学 
图 书馆 借 到 第 1 版 的 《Spring 实战 》， 当 时 忙于 毕业 ， 没 有 把 这 本 书 完 
整地 谈 完 ， 但 是 依赖 注入 、 面 同 切 面 编程 等 理念 还 是 深 深 印 在 了 脑海 
中 ， 书 中 经 典 有 趣 的 圆 昌 骑士 样 例 更 是 张 使 我 谈 了 很 多 相关 的 历史 背景 
材料 。 


屈指 算 来 ， 已 经 过 去 了 10 多 年 ，Spring 早 已 经 成 为 企业 级 Java 开 发 
的 事实 标准 ，Spring Boot 和 Spring Cloud 相 关 的 技术 引领 潮流 ， 更 是 成 
为 Java 工 程 师 的 必 备 技能 。《Spring 实 战 》 的 作者 Craig Walls 不 断 推 陈 
出 狐 ， 将 这 本 经 典 图 书 更 狐 到 第 5 版 。 只 是 ，10 多 年 以 前 ， 我 恕 怕 做 梦 
也 想不到 会 与 这 本 书 有 这 么 深 的 毕 分 。 


Spring 之 所 以 能 够 在 技术 不 断 更 新 换代 的 工 领域 长 盛 不 可， 并 且 引 
领 技 术 架 构 发 展 的 漳 流 ， 我 想 这 是 因为 它 一 直 没 有 仿 离 Rod Johnson 最 初 
的 目标 。 那 吏 定 ， 根 据 技 术 的 及 展 ， 不 断 优 化 和 音 新 ， 让 Java 应 用 的 开 
发 更 加 便利 和 高 效 。 从 XML 配置 、 注 解 配 置 ， 再 到 Spring Boot 的 目 动 化 
配置 ，Spring 在 不 断 简 化 ， 开 及 人 员 需 要 做 的 额外 工作 越 来 越 少 。 虽 然 
Rod Johnson 早 已 离开 Spring 去 开创 新 的 事业 了 ， 但 是 我 相信 Spring 的 这 
种 基因 还 是 一 直 在 的 。 在 可 以 预见 的 未 来 ，Spring 及 其 家 族 产品 依然 是 
全 得 化 时 间 投 资 学 习 的 扩 术 。 


有 时 候 ， 我 也 会 思考 ， 真 正 的 技术 到 压 是 什么 ， 是 某 一 项 生 侣 的 配 
置 还 是 某 个 新 的 API? 我 想 ， 这 都 是 技术 ， 却 不 是 最 关键 的 。 因 为 这 些 
东西 都 是 不 稳定 的 、 易 变 的 ， 想 要 在 新 知识 层 出 不 筋 的 领域 中 不 被 淘 
达 ， 我 们 更 应 该 去 退 求 一 些 内 在 稳定 不 变 的 知识 ， 比 如 技术 规范 、 设 计 
原理 等 。 所 以 ， 和 希望 本 书 的 读者 能 够 通过 这 本 入 门 的 读物 ， 去 更 多 地 探 
究 一 些 Spring 故 层 的 设计 和 实现 原理 。 


本 书 第 10 草 关于 反应 式 编程 的 初 称 由 何 品 翻 详 ， 我 负责 统称 修改 ; 
为 外 ， 对 于 反应 式 编程 的 术语 和 规范 ， 何 品 和 他 的 团队 部 做 了 很 多 的 工 
作 ， 在 此 疝 他 表示 感谢 。 


再 次 感谢 我 的 爱人 和 儿子 ， 文 容 奶 我 把 这 几 个 月 的 业余 时 间 都 耗 在 
了 笔记 本 电脑 的 前 面 。 


硕 望 这 本 书 对 谈 者 有 所 帮助 ， 如 果 恋 者 在 疯 恋 中 遇 到 问题 ， 可 以 通 
过 levinzhang1981 @126.com 或 者 微 信 levinzhang1981 与 我 联系 ， 祝 阅读 
愉快 。 


由 -下 演 


2019 年 7 月 29 日 于 大 连 


关于 本 书 


编写 《Spring 实战 〈 第 5 版 ) 》 的 目的 是 让 读者 学 会 使 用 Spring 框 
架 、Spring Boot 以 及 Spring 生 态 系 统 中 各 种 辅助 部 分 构建 令 人 赞叹 的 应 
用 程序 。 本 书 首先 介绍 如 何 使 用 Spring 和 Spring Boot 开 发 基于 Web、 以 
数据 库 作 为 后 端的 Java 应 用 ;随后 进行 必要 的 扩展 ， 展 现 如 何 与 其 他 应 
用 进行 集成 、 使 用 反应 式 类 型 进行 编程 ， 以 及 将 应 用 拆 分 为 离散 的 微服 
务 ; 了 最 后 讨论 如 何 准备 应 用 的 部 闭 。 


尽 官 Spring 生态 系统 中 的 每 个 项 目 和 都 提供 了 完善 的 文 要 ， 但 是 本 书 
所 做 的 是 所 有 参考 文档 部 无 法 做 到 的 事情 : 提供 一 个 实用 的 、 项 目 驱 动 
的 指南 ， 将 Spring 的 各 种 元 素 组 合 起 来 形成 一 个 真正 的 应 用 。 


谁 应 该 阅读 这 本 书 
《Spring 实 战 〈 第 5 版 ，》 适 用 于 刚刚 开始 学 习 Spring Boot 和 Spring 
框架 的 Java 开 有 友人 员 ， 也 适用 于 想 要 超越 基础 知识 并 学 习 Spring 新 特性 


的 经 验 丰 富有 的 Spring 开 发 者 。 


这 本 书 走 如 何 组 织 的 : 路 线 图 


第 1 部 分 涵盖 构建 Spring 应 用 的 基础 话题 。 


第 1 章 介 绍 Spring 和 Spring Boot 以 及 如 何 初 始 化 Spring 项 目 。 在 本 章 
中 ， 我 们 迈 出 构建 Spring 应 用 的 第 一 步 ， 在 本 书后 续 各 草 中 ， 我 们 
会 对 这 个 应 用 进行 扩展 。 

第 2 章 讨 论 如 何 使 用 Spring MVC 构 建 应 用 的 Web 层 。 在 本 章 中 ， 我 
们 将 会 构建 处 理 Web 请 求 的 控制 右 以 及 在 浏览 右 中 广 染 信息 的 视 
图 。 

第 3 章 会 深入 探讨 Spring 应 用 的 后 问 ， 在 这 里 数据 会 持久 化 到 关系 型 
数据 库 中 。 

在 第 4 章 中 ， 我 们 会 使 用 Spring Security 认 证 用 户 并 防止 未 认证 的 用 
户 访问 应 用 。 

第 5 章 介 绍 如 何 使 用 Spring Boot 的 配置 属性 功能 来 配置 Spring 应 用 。 
我 们 还 会 学 习 如 何 使 用 profile 选 择 性 地 应 用 配置 。 


第 2 部 分 讨论 如 何 将 Spring 应 用 与 其 他 应 用 进行 集成 。 


第 6 章 延 续 第 2 章 对 Spring MVC 的 讨论 ， 我 们 将 会 学 习 如 何在 Spring 
中 编写 REST API。 

第 7 章 讨 论 了 和 第 6 草 相 对 芯 的 主题 ， 展 现 Spring 应 用 如 何 消 强 REST 
APIl。 

第 8 章 会 讨论 如 何 使 用 异步 通信 技术 让 Spring 应 用 发 送 和 接收 消 忆 ， 
这 里 会 用 到 Java Message Service、RabbitMQ 或 Kafka。 

第 9 章 讨 论 如 何 使 用 Spring Integration 进 行 声 明 式 的 应 用 和 集成。 


第 3 部 分 探讨 Spring 对 反应 了 却 编 程 提 供 的 全 新 文 持 。 


第 10 章 介绍 Reactor 项 目 。 这 是 一 个 反应 式 编程 库 ， 文 撑 了 Spring 5 
的 反应 式 特 性 。 


阅读 


第 11 章 重新 探讨 REST API 开 及 ， 介 绍 全 新 的 Web 框 加 Spring 
WebFlux。 该 框架 借用 了 很 多 Spring MVC 的 理念 ， 但 是 为 Web 开 发 
提供 了 新 的 反应 式 模 型 。 

第 12 章 将 会 看 一 下 如 何 使 用 Spring Data 编 写 反 应 式 数据 持久 化 ， 我 
们 将 会 谈 取 和 写 入 Cassandra 与 Mongo 数 据 库 。 


第 4 部 分 将 会 拆 分 单 体 应 用 模型 ， 介 绍 Spring Cloud 和 微服 务 开 发 。 


第 13 章 会 深入 介绍 服务 发 现 ， 组 合 使 用 Spring 和 Netflix 的 注册 中 心 
实现 Spring 敏 服务 的 注册 和 发现 。 

第 14 草 将 展现 如 何在 配置 服务 需 中 实现 中 心 化 的 应 用 配置 ， 从 而 实 
现 跨 微服 务 共 至 配置 。 

第 15 章 会 介绍 Hystrix 的 断路 需 模 式 。 它 能 够 让 微服 务 在 面临 失败 时 
更 有 弹性 。 


在 第 5 部 分 中 ， 我 们 将 会 讨论 如 何 做 好 将 应 用 投入 生产 环境 的 准 
并 看 一 下 如 何 进 行 部 著 。 


第 16 半 会 介绍 Spring Boot Actuator。 它 古 Spring Boot 的 一 个 扩展 ， 
通过 REST 端 点 的 形式 暴露 Spring 应 用 内 部 的 运行 状况 。 

第 17 草 将 会 介绍 如 何 使 用 Spring Boot Admin。 它 是 构建 在 Actuator 
之 上 的 一 个 用 户 友 好 的 基于 浏览 右 的 管理 应 用 。 

第 18 和 章 将 会 讨论 如 何 将 Spring bean 骏 露 为 JMX MBean 以 及 如 何 消 费 
yi 

在 第 19 半 中 ， 我 们 会 看 到 如 何 将 Spring 应 用 部 著 a 到 各 种 生产 环境 

中 。 


通常 来 讲 ， 刚 刚 接触 Spring 的 开发 人 员 应 该 从 第 1 章 开 始 ， 并 按 顺序 
每 一 章 ， 经 验 丰 富 的 Spring 开 发 人 员 可 能 更 愿意 在 任何 感 兴趣 的 时 


候 参 与 进来 。 即 便 如 此 ， 每 一 章 都 是 建立 在 前 一 草 内 容 的 基础 上 的 ， 所 
以 如 果 从 中 间 开 始 阅 读 ， 那 么 可 能 会 源 挥 一 些 上 下 文 信息 。 


关于 代 但 


本 书包 人 名 许多 源 代 码 的 样 例 ， 有 的 是 编号 的 程序 清单 ， 有 的 是 并 通 
文本 内 购 的 源码 。 在 这 两 种 情况 下 ， 源 代码 部 使 用 固定 完 度 的 字体 排 
版， 以 全 将 其 与 普通 文本 分 开 。 有 时 代码 也 会 使 用 粗 体 显示 ， 以 便于 强 
调 此 处 代码 与 本 草 前 面 步 又 的 变更 ， 比 如 为 已 有 的 代码 行 讨 加 新 的 特 
js 


在 许多 情况 下 ， 原 始 源 代 码 会 重新 格式 化 ;我 们 添加 了 换行 符 和 重 
新 缩 进 ， 以 适应 书 中 可 用 的 页 面 空间 。 在 极 少数 情况 下 ， 这 样 做 依然 是 
不 够 的 ， 在 这 种 情况 下 程序 清单 会 包括 换行 符 (we)。 此 外 ， 当 在 文中 描 

述 代 码 的 时 候 ， 源 码 中 的 注释 通常 会 伞 移 除 。 许 多 程序 清单 会 有 代码 标 
注 ， 用 来 突出 强调 重要 的 概念 。 


本 书 中 样 例 的 源码 可 以 通过 异步 社区 的 本 书页 面 下 载 。 
其 他 在 线 资 源 
Spring 的 Web 站 点 有 很 多 有 用 的 起 步 指 南 《〈 其 中 一 部 分 吏 是 由 本 书 


的 作者 编写 的 ) 。 
StackOverflow 上 的 Spring 标签 和 Spring Boot 是 一 个 询问 Spring 问题 


和 玉 助 别人 的 好 地 方 。 攻 助 解决 别人 的 Spring 问题 是 学 习 Spring 的 
好 办 法 。 


天 于 作者 


克 雷 格 : 添 斯 (Craig Walls) 是 Pivotal 的 首席 工程 师 。 他 是 Spring 框 
架 的 热心 推动 者 ， 经 音 在 本 地 用 户 组 和 会 议 上 及 言 ， 握 与 天 于 Spring 的 
文章 。 在 不 琢磨 代码 的 时 候 ，Craig 正 在 计划 去 迪士尼 世界 或 迪士尼 乐 
园 的 下 一 次 旅行 ， 他 和 希望 尽 可 能 多 地 陪伴 他 的 受 子 和 两 个 女儿 。 


关于 封面 


《Spring 实战 〈 第 5 成 ) 》 的 封面 人 物 是 “Le Caraco”， 也 束 是 约旦 西 
两 部 卡拉 克 〈Karak) 省 的 后 民 。 充 省 的 首府 是 Al-Karak， 那 里 的 山顶 
有 雁 城 八 ， 对 死海 和 周边 的 平原 有 看 极 佳 的 视 寻 。 这 幅 图 出 目 1796 年 出 
版 的 法 国旅 游 图 书 ，Encyclopédiedes Voyages， 由 J.G.St.Sauveur 编 写 。 
在 那 时 ， 为 了 如 乐 而 去 旅游 还 是 相对 新 鲜 的 做 法 ， 而 像 这 样 的 旅游 指南 
是 很 流行 的 ， 它 能 够 让 旅行 家 和 是 不 出 户 的 人 们 了 解法 国 其 他 地 区 和 
外 的 夺 民 。 


Encyclopédiedes Voyages 中 多 种 多 样 的 图 男生 动 摘 绘 了 200 年 前 世界 
上 各 个 城镇 和 地 区 的 独特 魅力 。 在 那 时 ， 相 隔 几 十 千 米 的 两 个 地 区 痢 琴 
束 不 相同 ， 可 以 通过 看 闻 判 晰 人 们 所 葛 属 于 哪个 地 区 。 这 本 旅行 指 两 展 
现 了 那个 时 代 和 其 他 历史 时 代 的 隔离 感 和 距离 感 ， 这 与 我 们 这 个 运动 过 
度 的 时 代 是 截然 不 同 的 。 


从 那 以 后 ， 服 雄风 格 及 生 了 改变 ， 曙 有 地 方 特色 的 多 样 性 开始 洗 
化 。 现 在 ， 有 时 很 难说 一 个 洲 的 大 民 和 其 他 洲 的 大 民有 什么 不 同 。 可 
能 ， 从 积极 的 方面 来 看 ， 我 们 用 原来 文化 和 视觉 上 的 多 样 性 换 来 了 个 人 
风格 的 多 变性 ， 或 者 可 以 说 是 更 为 多 样 化 和 有 趣 的 知识 科技 生活 。 这 本 
旅行 指南 中 的 图 片 反映 了 两 个 世纪 前 各 个 地 区 生活 的 多 样 性 ， 我 们 现在 
用 图 书 封 面 的 方式 对 其 进行 了 再 现 。Manning 出 版 社 的 员工 都 认为 这 是 
计算 机 行业 中 一 个 很 有 意思 的 创意 。 


大 SR 


有 百 


在 使 用 了 Spring 15 年 并 编写 了 这 本 书 的 5 个 版 本 (暂时 不 算 《Spring 
Boot 实 战 》 了 ) 之 后 ， 你 可 能 会 认为 ， 在 为 这 本 书 撰 与 前 言 时 ， 我 很 难 
想 出 一 些 关 于 Spring 令 人 兴奋 的 新 内 容 ， 但 事实 远 非 如 此 ! 


在 Spring 生态 系统 中 ，Spring、Spring Boot 和 所 有 其 他 项 目的 每 个 版 
本 都 发 布 了 令 人 兴奋 的 新 功能 ， 重 新 点 燃 了 开发 应 用 程序 的 乐趣 。 
Spring 5.0 和 Spring Boot 2.0 的 发 布 达 到 了 一 个 重要 的 里 程 碑 。Spring 有 了 了 
更 多 的 乐趣 ， 所 以 编写 新 版 《Spring 实 战 》 是 很 容易 的 。 


Spring 5 的 主要 功能 是 对 反应 式 编程 的 文 持 ， 包 括 Spring WebFlux。 
这 是 一 个 全 新 的 反应 式 Web 框 架 ， 借 鉴 了 Spring MVC 的 编程 模型 ， 人 允许 
开 及 人 员 创 建 伸缩 性 更 好 且 耗 用 更 少 线 程 罗 Web 应 用 程序 。 全 于 Spring 
应 用 的 后 端 ， 最 新 版 本 的 Spring Data 支持 创建 反应 式 、 非 阻塞 的 数据 
repository。 所 有 这 些 都 构建 在 Reactor 项 目 之 上 ，Reactor 是 一 个 用 于 处 
理 反 应 式 类 型 的 Java 库 。 


除了 Spring 5 新 的 反应 式 编 程 特 性 之 外 ，Spring Boot 2 提供 了 比 以 前 
更 多 的 目 动 配置 文 持 ， 以 及 一 个 完全 重新 设计 的 Actuator， 用 于 探 碍 和 
操作 正在 运行 的 应 用 。 


更 童 要 的 是 ， 当 开 友 人 员 布 望 将 单 体 应 用 拆 分 为 分 秘 的 做 服务 时 ， 
Spring Cloud 提 供 了 一 些 工 具 ， 使 配置 和 友 现 微服 务 变 得 容易 ， 并 增强 


了 微服 务 的 功能 ， 使 它们 更 能 抵御 失败 。 


我 很 高 兴 地 说 ，《Spring 实 战 〈 第 5 版 ) 》 涵 盖 了 所 有 的 这 些 功能 ， 
其 至 更 多 ! 如 果 你 是 经 验 丰 是 的 老手 ，《Spring 实 战 〈 第 5 版 )》 可 以 作 
为 指南 ， 指 导 你 去 学 习 Spring 提 供 的 新 功能 ， 如 果 你 是 Spring 新 手 ， 那 
么 现在 是 行动 起 来 的 最 佳 时 机 ， 本 书 的 前 儿 章 会 让 你 快速 上 手 ! 


与 Spring 合 作 有 的 15 年 是 令 人 兴 否 的 。 现 在 我 已 经 写 了 5 个 版 本 的 
《Spring 实 战 》， 我 很 想 和 你 们 分 对 这 份 兴 否 ! 


致谢 


Spring 和 Spring Boot 所 做 的 最 令 人 尺 奇 的 事情 之 一 吏 是 目 动 为 应 用 
程序 提供 所 有 的 基础 功能 ， 让 开 友 人 员 专 注 于 应 用 程序 特有 的 地 辑 。 不 
芋 的 是， 对 于 写 书 这 件 事 来 说 ， 并 没有 这 样 的 魔法 。 和 是 这 样 的 吗 ? 


在 Manning， 有 很 多 人 在 施展 “魔法 ”， 确 保 这 本 书 是 最 好 的 。 特 别 
要 感谢 我 的 项 目 编辑 Jenny Stout 以 及 制作 团队 ， 其 中 包括 项 目 主 管 Janet 
Vail、 文 字 编 辑 Andy Carroll 和 Frances Buran， 以 及 校对 Katie Tennant 和 
Melody Dolab。 同 时 也 要 感谢 技术 校对 Joshua White， 他 的 工作 很 全 
面 ， 很 有 帮助 。 


人 在 此 过 程 中 ， 我 们 得 到 了 儿 位 同行 评论 的 有 反馈， 他 们 确 你 了 这 本 书 
没有 偏离 目标 ， 泣 盖 了 正确 的 内 容 。 为 此 ， 我 要 感谢 Andrea Barisone、 
Arnaldo Ayala、 Bill Fly、 Colin Joyce、Daniel Vaughan、David 
Witherspoon、 Eddu Melendez、 lIain Campbell、Jettro Coenradie、John 
Gunvaldson、 Markus Matzker、Nick Rakochy、Nusry Firdousi、 Piotr 
Kafel、 Raphael Villela、Riccardo Noviello、Sergio Fernandez Gonzalez、 
Sergiy Pylypets、 Thiago Presa、Thorsten Weber、Waldemar 
Modzelewski、 Yagiz Erkan 和 Zeljko Trogrlic。 


和 往常 一 样 ， 如 果 不 是 Spring 工 程 团 队 成 员 所 做 的 出 色 工作 ， 写 这 
本 书 是 没有 任何 意义 的 。 我 惊叹 于 你 们 所 创造 的 成 果 ， 并 期 待 未 来 继续 


改变 软件 开 友 的 方式 。 


非常 感谢 我 的 同行 们 在 No Fluff/Just Stuff 巡 回 演讲 上 的 发 言 。 我 从 
你 们 每 个 人 身上 学 到 很 多 。 我 特别 要 感谢 Brian Sletten、Nate Schutta 和 
Ken Kousen 关 于 Spring 的 对 话 和 和 邮件， 这些 内 容 塑 造 了 这 本 书 。 


我 要 再 次 感谢 Phoenicians， 你 们 太 棒 了 辆 。 


最 后 ， 我 要 感谢 我 美丽 的 妻子 Raymie。 她 是 我 生命 中 的 丽 爱 ， 是 我 
最 甜蜜 的 梦想 ， 也 是 我 的 灵感 来 源 ， 谢谢 你 的 或 励 ， 也 谢谢 你 为 这 本 新 
书 做 的 努力 。 致 我 可 爱 的 女儿 Maisy 和 Madi: 我 为 你 们 感到 骄傲 ， 为 你 
们 即将 成 为 了 不 起 的 年 轻 女 士 感 到 骄 做 。 我 对 你 们 的 爱 超出 了 你 们 的 想 
象 ， 也 超出 了 我 语言 所 能 表达 的 程度 。 


[1] Phoenicians 指 的 是 远古 时 代 的 腓 尼 基 人 ， 他 们 被 认为 是 字母 系统 的 
创建 者 ， 基 于 字母 的 所 有 现代 语言 都 是 由 此 衍生 而 来 的 。 在 迪士尼 世界 
的 Epcot， 有 名 为 Spaceship Earth 的 时 光 穿 梭 体 验 ， 我 们 可 以 了 解 到 人 类 
交流 的 历史 ， 其 至 能 够 回 到 腓 尼 基 人 的 时 代 ， 在 这 段 旅 程 的 券 日 中 这 样 
说 道 : 如 果 你 觉得 学 习 字 苹 语 言 很 容 多 ， 束 感谢 腓 尼 基 人 吧 ， 是 他 们 友 
明了 它 。 这 是 作者 的 一 种 幽默 说 法 。 一 一 详 者 注 


和 资源 与 文 持 
本 书 由 异步 社区 出 品 ， 社 区 (https://www.epubit.com/〉 为 您 提供 相 
关 资 源 和 后 续 服 务 。 
配套 资源 
本 书 提 供 如 下 资源 : 
。 本 书 源 代码 ; 


。 书 中 彩 图 文件 。 





要 获得 以 上 配套 资源 ， 请 在 异步 社区 本 书页 面 中 点 击 W 守 于， 下 
转 到 下 载 界 面 ， 按 近 示 进行 操作 即 可 。 注 意 : 为 保证 购书 读者 的 权益 ， 
该 操作 会 给 出 相关 提示 ， 要 求 输 入 提取 公 进 行 验证 。 


如 末 和 您 是 教师 ， 硕 望 获得 教学 配套 资源 ， 请 在 社区 本 书页 面 中 直接 
联系 本 书 的 贡 任 编辑 。 


提交 勘误 


作者 和 编辑 尽 最 大 努力 来 确 人 书 中 内 容 的 准确 性 ， 但 难免 会 存在 下 
闫 。 欢 迎 您 将 友 现 的 问题 反馈 给 我 们 ， 玫 助 我 们 近 升 图 书 的 质量 。 


当 您 肥 现 错误 时 ， 请 登录 寞 步 社 区 ， 按 书 名 搜索 ， 进 入 本 书页 面 ， 
扩 击 “提交 翰 误 "”， 输 入 动 误 信息 ， 扣 击 “ 近 区” 按钮 即 可 。 本 书 的 作者 和 
编辑 会 对 您 所 交 的 勘误 进行 审核 ， 确 认 并 接受 后 ， 您 将 获 赠 异步 社区 的 
100 积 分 。 积 分 可 用 于 在 异步 社区 兄 换 优惠 错 、 样 书 或 奖品 。 





与 我 们 联系 
我 们 的 联系 邮箱 是 contact@epubit.com.cn。 
如 果 您 对 本 书 有 任何 疑问 或 建议 ， 请 您 发 邮件 给 我 们 ， 并 请 在 邮件 
标题 中 注 明 本 书 书 名 ， 以 便 我 们 更 高 效 地 做 出 反馈 。 


如 末 和 您 有 兴趣 出 版 图 书 、 孙 制 教学 视频 ， 或 者 参与 图 书 翻 诺 、 拉 术 
审 校 等 工作 ， 可 以 有 邮件 给 我 们 ， 有 意 出 版 图 书 的 作者 也 可 以 到 并 步 社 
区 在 线 提 交 投 稿 〈 直 接 访 问 www.epubit.comy selfpublish/submission 即 
可 ) 。 


如 果 学 校 、 培 训 机 构 或 企业 想 批量 购买 本 书 或 异步 社区 出 版 的 其 他 
图 书 ， 也 可 以 友 邮 件 给 我 们 。 


如 果 您 在 网 上 友 现 有 和 针对 异步 社区 出 品 图 书 的 各 种 形式 的 盗版 行 
为 ， 包括 对 图 书 全 部 或 部 分 内 容 的 非 授 权 传 播 ， 请 您 将 怀疑 有 侵权 行为 
的 链接 发 邮件 给 我 们 。 您 的 这 一 举动 是 对 作者 权益 的 保护 ， 也 是 我 们 持 
续 为 您 提供 有 价值 的 内 容 的 动力 之 源 。 


关于 弄 步 社区 和 弄 步 图 书 


“异步 社区 * 是 人 民 邮 电 出 版 社 旗下 IT 专业 图 书社 区 ， 致 力 于 出 版 精 
品 IT 技术 图 书 和 相关 学 习 产品 ， 为 作 译 者 提供 优质 出 版 服务 。 异 步 社 区 
创办 于 2015 年 8 月 ， 提 供 大 量 精品 IT 技术 图 书 和 电子 书 ， 以 及 高 品质 技 
术 文章 和 视频 课程 。 更 多 详情 请 访问 异步 社区 官网 


https:/www.epubit.com 。 


“ 腊 步 图 书 ” 是 由 弄 步 社区 编辑 团队 束 划 出 版 的 精品 开 专 业 图 书 的 蜗 
路 ， 依 托 于 人 民 邮 电 出 版 社 近 30 年 的 计算 机 图 书 出 版 积 索 和 专业 编辑 团 
队 ， 相 关 图 书 在 封 徊 上 印 有 异步 图 书 的 LOGO。 和 异步 图 书 的 出 版 领域 包 
括 软 件 开发 、 大 数据 、AI、 测 试 、 前 端 、 网 络 技术 等 。 





微 信 服务 号 


第 1 部 分 “Spring 基础 


本 书 的 第 1 部 分 将 会 介绍 如 何 开 始 编写 Spring 应 用 ， 并 在 这 个 过 程 中 
尝 习 Spring 的 基础 知识 。 


在 第 1 章 中 ， 我 将 简要 介绍 Spring 和 Spring Boot 的 核心 知识 ， 并 展 
示 在 构建 第 一 个 Spring 应 用 Taco Cloud 的 过 程 中 如 何 初 始 化 Spring 项 目 。 
在 第 2 章 中 ， 我 们 将 深入 研究 Spring MVC， 了 解 如 何在 浏览 器 中 显示 模 
一 数据 ， 以 及 如 何 处 理 和 验证 表单 竹 入 。 我 们 还 会 介绍 选择 视图 模板 库 
的 技巧 。 在 第 3 章 中 ， 我 们 将 同 Taco Cloud 应 用 程序 添加 数据 持久 化 功 
能 。 到 时 候 ， 我 们 将 介绍 如 何 使 用 Spring 的 JDBC 模 板 来 插入 数据 ， 以 及 
如 何 使 用 Spring Data 声 明 JPA repository。 第 4 章 将 介绍 Spring 应 用 程序 的 
安全 性 ， 包 括 目 动 配置 Spring 安全 性 、 声 明 目 定 义 用 户 存 储 、 目 定义 登 
录 页 面 以 及 防止 跨 站 请 求 伪造 (CSRF) 攻击 。 作 为 第 1 部 分 的 结尾 ， 我 
们 将 在 第 5 和 章 中 学 习 配 置 属性 。 我 们 将 了 解 如 何 细 粒 度 调 整 目 动 配置 
bean、 让 应 用 组 件 使 用 配置 属性 ， 以 及 如 何 使 用 Spring profile。 


第 1 章 ”Spring 起 步 


。 Spring 和 Spring Boot 的 必 备 知识 


e。 初始 化 Spring 项 目 


。 Spring 生 态 系 统 概 哆 





尽管 希腊 哲学 家 赫 拉 克利 特 〈(Heraclitus 〉 并 不 作为 一 名 软件 开发 人 
员 而 闻名 ， 但 他 似乎 深 请 此 道 。 他 的 一 句 话 经 党 被 引用 :“ 唯 一 不 变 的 
束 是 变化 ”， 这 人 句 话 抓 住 了 软件 开 及 的 真 详 。 


我 们 现在 开 及 应 用 的 方式 和 1 年 前 、5 年 前 、10 年 前 都 是 不 同 的 ， 更 
别提 15 年 前 了 ， 当 时 Rod Johnson 的 图 书 Expert One-on-One J2EFE Design 
and Development 修 绍 了 Spring 框架 的 初始 形态 。 


当时 ， 节 稍 见 的 应 用 形式 征 基 于 浏览 磺 的 Web 应 用 ， 后 器 由 关系 型 


数据 库 作 为 支撑 。 尽 管 这 种 形式 的 开发 依然 有 它 的 价值 ，Spring 也 为 这 
种 应 用 提供 了 良好 的 支持 ， 但 是 我 们 现在 感 兴趣 的 还 包括 如 何 开发 面向 


云 的 由 微服 务 组 成 的 应 用 ， 这 些 应 用 会 将 数据 你 存 到 各 种 类 型 的 数据 库 
中 。 万 外 一 个 思 新 的 关注 氮 是 反应 却 纺 程 ， 它 致力 于 通过 非 阻 故 操 作 授 
供 更 好 的 扩展 性 并 提升 性 能 。 


随 看 软件 开发 的 发 展 ，Spring 框 架 也 在 不 断 变 化 ， 以 解决 现代 应 用 
开发 中 的 问题 ， 其 中 就 包括 微服 务 和 反应 式 编 程 。Spring 还 通过 引入 
Spring Boot 人 简化 目 己 的 开发 模型 。 


不 管 你 是 开发 以 数据 库 作 为 文 撑 的 简单 Web 应 用 ， 还 是 围 经 人 微服 务 
构建 一 个 现代 应 用 ，Spring 框 架 都 能 帮助 你 达成 目标 。 本 章 是 使 用 
Spring 进行 现代 应 用 开 有 友 的 第 一 步 。 


1.1 什么 定 Spring 


我 知道 你 现在 可 能 迫不及待 地 想 要 开始 编写 Spring 应 用 了 ， 我 可 以 
回 你 傈 证， 在 本 章 结束 之 前 ， 你 肯定 能 够 开 有 太一 个 向 单 的 Spring 应 用 。 
自 完 ， 我 将 使 用 Spring 的 一 些 基 础 概念 为 你 搭建 一 个 舞台 ， 帮 助 你 理解 
Spring 是 如 何 运 行 起 来 的 。 


任何 实际 的 应 用 程序 都 是 由 很 多 组 件 组 成 的 ， 每 个 组 件 负责 整个 应 
用 功能 的 一 部 分 ， 这 些 组 件 十 要 与 其 他 的 应 用 元 系 进行 协调 以 完成 目 己 
的 任务 。 当 应 用 程序 运行 时 ， 需 要 以 东 种 方式 创建 并 引入 这 些 组 件 。 


Spring 的 核心 是 提供 了 一 个 容 需 〈container) ， 通 第 称 为 Spring 应 用 
上 和 下文 〈Spring application context) ， 它 们 会 创建 和 管理 应 用 组 件 。 这 
些 组 件 也 可 以 称 为 bean， 会 在 Spring 应 用 上 下 文中 装配 在 一 起 ， 从 而 形 


成 一 个 完整 的 应 用 程序 。 这 吏 像 配 卖 、 人 砂浆、 木材、 管道 和 电线 组 合 在 
一 起 ， 形 成 一 栋 房 子 似 的 。 


将 bean 玫 配 在 一 起 的 行为 是 通过 一 种 基于 依赖 注入 〈dependency 
injection，DI) 的 模式 实现 的 。 此 时， 组 件 不 会 再 去 创建 它 所 依赖 的 组 
件 并 管理 它们 的 生命 周期 ， 使 用 依赖 注入 的 应 用 依赖 于 单独 的 实体 〈 容 
和 蓝 ) 来 创建 和 维护 所 有 的 组 件 ， 并 将 其 注入 到 需要 它们 的 bean 中 。 通 
前 ， 这 是 通过 构造 磊 参 数 和 属性 访问 方法 来 实现 的 。 


举例 来 说 ， 假 设 在 应 用 的 众多 组 件 中 ， 有 两 个 是 我 们 需要 处 理 的 : 
库存 服务 (用 来 获取 库存 水 平 ) 和 商品 服务 “用 来 提供 基本 的 商品 信 
思 ) 。 丙 品 服务 需要 依赖 于 库存 服务 ， 这 样 它 才能 提供 商品 的 完整 信 
轧 。 风 1.1 曾 述 这 些 beaan 和 Spring 应 用 上 下 文 之 间 的 关系 。 


Spring 应 用 上 下 文 


注入 到 





图 1.1 应 用 组 件 通过 Spring 的 应 用 上 下 文 来 进行 管理 并 实现 互相 注入 


在 核心 容 右 之 上 ，Spring 及 其 一 系列 的 相关 库 提 供 了 Web 框 染 、 各 
种 持久 化 可 选 方案 、 安 全 框架 、 与 其 他 系统 集成 、 运 行 时 监控 、 微 服务 


文 持 、 反 应 却 编 程 以 及 众多 现代 应 用 开 及 所 需 的 特性 。 


在 历史 上 ， 指 导 Spring 应 用 上 下 文 将 bean 妆 配 在 一 起 的 方式 是 使 用 
一 个 或 多 个 XML 文件 〈 描 述 各 个 组 件 以 及 它们 与 其 他 组 件 的 关联 天 
系 ) 。 例 如 ， 如 下 的 XML 描述 了 两 个 bean， 也 就 是 InventoryService bean 
和 ProductService bean， 并 有 通过 构造 硕 参 数 将 InventoryService 痿 配 到 了 


ProductService 中 : 


<bean id="inventoryService" 
class="com.example.InventoryService” /> 


<bean id="productService" 
class="com.example.ProductService” /> 
<constructor-arg ref="inventoryService” /> 
</bean> 





但 是 ， 在 最 近 的 Spring 版 本 中 ， 基 于 Java 的 配置 更 为 弟 见 。 如 下 基 
于 Java 的 配置 类 是 与 XML 配 置 等 价 的 : 


Q@Configuration 
public class ServiceConfiguration { 
QBean 
public InventoryService inventoryService() { 
return new InventoryServicel( ); 


} 


QBean 
public ProductService productService() { 
return new ProductService(inventoryService() ) ; 
} 
} 





(@Configuration 注 解 会 告知 Spring 这 是 一 个 配置 类 ， 会 为 Spring 应 用 
上 下 文 提 供 bean。 这 个 配置 类 的 方法 使 用 @Bean 注 解 进行 了 标注 ， 表 明 
这 些 方法 所 返回 的 对 象 会 以 bean 的 形式 添加 到 Spring 的 应 用 上 下 文中 


(默认 情况 下 ， 这 些 bean 所 对 应 的 bean ID 与 定义 它们 的 方法 名 称 是 相同 
的 ) 。 


相对 于 基于 XML 的 配置 方式 ， 基 于 Java 的 配置 会 市 来 多 项 额外 的 收 
蔓 ， 包 括 更 强 的 类 型 安全 性 以 及 更 好 的 重 构 能 力 。 即 便 如 此 ， 不 管 是 使 
用 Java 还 征 使 用 XML 的 野 却 配置 ， 只 有 当 Spring 不 能 进行 目 动 配置 的 时 
候 才 二 必要 的 。 


在 Spring 技术 中 ， 目 动 配 置 起 源 于 所 谓 的 目 动 痛 配 〈autowiring) 和 
组 件 扫 描 (component scanning) 。 倍 助 组 件 扫 摘 技术 ，Spring 能 够 目 动 
及 现 应 用 其 路 径 下 的 组 件 ， 并 将 它们 创建 成 Spring 应 用 上 下 文中 的 
bean。 倍 助 目 动 痛 配 技术 ，Spring 能 够 目 动 为 组 件 注 入 它们 所 依 顿 的 其 
他 bean。 


最 这 ， 随 看 Spring Boot 的 引入 ， 目 动 配置 的 能 力 已 经 远 远 超出 了 组 
件 扫 摘 和 目 动 装配 。Spring Boot 是 Spring 框架 的 扩展 ， 提 供 了 很 多 增强 
生产 效率 的 方法 。 最 为 大 家 所 贺 知 的 增 蝇 方法 束 是 目 动 配 置 
Cautoconfiguration) ，Spring Boot 能 够 基于 半路 径 中 的 和 条目、 环境 芍 量 
和 其 他 因 系 合理 猜测 需要 配置 的 组 件 并 将 它们 北 配 在 一 起 。 


我 非 营 愿意 为 你 展现 一 些 关 于 目 动 配置 的 示例 代码 ， 但 是 我 做 不 
到 。 目 动 配置 束 像 风 一 样 ， 你 可 以 看 到 它 的 效 素 ， 但 是 我 找 不 到 代码 指 
给 你 说, “看 ! 这 束 是 目 动 配置 的 样 例 ! ”事情 肥 生 了 ， 组 件 司 用 了 ， 蕊 
能 也 提供 了， 但 是 不 用 编写 任何 代码 。 没 有 代码 就 是 目 动 装配 的 本 质 ， 
也 是 它 如 此 美妙 的 原因 所 在 。 


Spring Boot 大 幅度 减少 了 构建 应 用 所 需 的 显 式 配置 的 数量 (不 官 是 
XML 配置 还 是 Java 配 置 ) 。 实 际 上 ， 当 完成 本 章 的 样 例 时 ， 我 们 会 有 一 
个 可 运行 的 Spring 心 用 ， 访 应 用 只 有 一 行 Spring 配置 代码 o 


Spring Boot 极 大 地 改善 了 Spring 的 开发 ， 因 此 很 难 想 象 在 没有 它 的 
情况 下 如 何 开 发 Spring 应 用 。 因 此 ， 本 书 会 将 Spring 和 Spring Boot 当 成 一 
回 事 。 我 们 会 尽 可 能 多 地 使 用 Spring Boot， 只 有 在 必要 的 时 候 才 使 用 显 
式 配 置 。 因 为 Spring XML 配置 是 一 种 过 时 的 方式 ， 所 以 我 们 主要 关 广 
Spring 基于 Java 的 配置 。 


亲 言 少 竹 ， 既 然 本 书 的 名 称 中 包含 “ 实 成 ?这 个 词 ， 那 么 殉 开 始 动手 
吧 ! 下 面 我 们 将 会 编写 使 用 Spring 的 第 一 个 应 用 。 


1.2” 仍 始 化 Spring 心 用 


在 本 书 中 ， 我 们 将 会 创建 一 个 名 为 Taco Cloud 的 在 线 应 用 ， 它 能 够 
人 种 美味 ， 也 就 是 墨西哥 前 玉米 卷 (taco) 由。 当 

， 在 这 个 过 程 中 ， 为 了 达成 我 们 的 目标 ， 我 们 将 会 用 到 Spring、 
Spring Boot 以 及 各 种 相关 的 库 和 框架 。 


我 们 有 多 种 初始 化 Spring 应 用 的 可 选 方案 。 尽 管 我 可 以 教 你 手动 创 
建 项 目 日 录 结 构 和 定义 构建 规范 的 各 个 步 又 ， 但 这 无 疑 古 浪费 时 间 ， 我 
们 最 好 将 时 间 论 在 编写 应 用 代码 上 。 因 此 ， 我 们 将 会 学 习 如 何 使 用 
Spring Initializr 和 初始 化 应 用 。 


Spring Initializr 是 一 个 基于 浏览 右 的 web 应 用 ， 同 时 也 是 一 个 REST 


API， 能 够 生成 一 个 Spring 项 目 结构 的 骨架 ， 我 们 还 可 以 使 用 各 种 想 要 
的 功能 来 填充 它 。 使 用 Spring Initializr 的 儿 种 方式 如 下 : 


。 通过 地 址 为 https://start.spring.io/ 的 Web 应 用 : 
。 在 命令 行 中 使 用 curl 命 令 ; 

。 在 命令 行 中 使 用 Spring Boot 命 令 行 接口 ; 

。 在 Spring Tool Suite 中 创建 新 项 目 ; 

。 在 IntelliJj IDEA 中 创建 新 项 目 ; 

。 在 NetBeans 中 创建 新 项 目 。 


我 将 这 些 细 节 放 到 了 附录 中 ， 这 样 承 不 用 在 这 里 花费 很 多 页 的 篇 幅 
介绍 每 种 方案 了 。 在 本 草 和 本 书 中 ， 我 都 会 癌 你 展示 如 何 使 用 我 最 钟爱 
的 方式 创建 新 项 目 : 在 Spring Tool Suite 中 使 用 Spring Initializr。 


顾名思义 ，Spring Tool Suite 是 一 个 非常 棱 的 Spring 开 发 环境 。 它 同 
时 还 提供 了 便利 的 Spring Boot Dashboard 特 性 ， 这 个 特性 是 其 他 IDE 都 不 
具备 的 〈 至 少 在 我 编 与 本 书 的 时 候 如 此 ) 。 


如 果 你 不 是 Spring Tool Suite 用 户 ， 那 也 没有 关系 ， 我 们 依然 可 以 做 
朋友 。 你 可 以 跳 转 到 附录 中 ， 玛 看 最 适合 你 的 Pnitializr 方 案 ， 以 此 来 蔡 
换 后 面 小 方 中 的 内 容 。 但 是 ， 在 本 书 中 ， 我 偶 尔 会 提 到 Spring Tool Suite 
特有 的 特性 ， 比 如 Spring Boot Dashboard。 如 果 你 不 使 用 Spring Tool 
Suite， 那 么 需要 调整 这 些 指令 以 适 配 你 的 IDE。 


1.2.1 使 用 Spring Tool Suite 和 初始 化 Spring 项 目 


要 在 Spring Tool Suite 中 初始 化 一 个 新 的 Spring 项 目 ， 我 们 首先 要 点 


Te 选择 New， 接 下 来 选择 Spring Starter Project。 图 1.2 展 现 了 
合 找 的 末 蛙 结构 。 





氢 Spring Tool Suite File Edit Source Refactor Navigate Search Project Run Window Help 
Oe New NBHEN 
号 ， imi@:EF OpenfFile... 





全 Spring Starter Project 
| DD Open Projects from File System 
40 局 Package Explorer 多 


Close 
译 Close All 


(二 Import Spring Getting Started Content 
( 漠 Spring Legacy Project 

起 Java Project 

sa Static Web Proiect 


图 1.2 ”在 Spring Tool Suite 中 使 用 Initializr 礼 始 化 一 个 新 项 目 


在 选择 Spring Starter Project 之 后 ， 将 会 出 现 一 个 新 的 同 导 对 话 框 
( 见 图 1.3) 


一 些 项 目的 通用 信息 ， 比 如 项 目 名 
称 、 挡 述 和 其 他 必要 的 信息 。 如 果 你 熟悉 Maven pom.xml 文 件 的 内 容 

束 可 以 识别 出 大 多 数 的 输入 域 条 目 最 终 都 会 成 为 Maven 的 构建 规范 。 对 
于 Taco Cloud 应 用 来 说 ， 我 们 可 以 按照 图 1.3 的 样子 来 填 宛 对 话 框 。 


o 同 导 的 第 一 人 页 会 询 问 一 


New Spring Starter Project (0) 


Name taco-cloud| 
Use default location 


Location 


Typ M | Packaging J | 
Java V 1.8 3 Languag J “ 
Group 
Artifact taco-cloud 
Version 0.0.1-SNAPSHOT 
Descri ption Taco Cloud Exampl 
Package tacos 
Working sets 
Add project to working sets New... 
Working sets: 
3 Cancel 


图 1.3 ”为 Taco Cloud 应 用 指定 通用 的 项 目 信 息 


器 叶 的 下 一 页 会 让 我 们 选择 要 添加 到 项 目 中 的 依赖 〈 见 图 1.4) 。 
注意 ， 在 对 话 框 的 项 部， 我 们 可 以 选择 项 目 要 基于 哪个 Spring Boot 版 
本 。 它 的 默认 值 是 最 淅 的 可 用 版 本 。 一 上 般 情 况 下 ， 最 好 使 用 这 个 献 认 的 
值 ， 际 非 你 需要 使 用 不 同 的 版 本 。 


至 于 依赖 项 本 里， 你 可 以 打开 各 个 区 域 并 查找 所 需 的 依赖 项 ， 也 可 
以 在 Available 机 部 的 搜索 框 中 对 依赖 进行 搜索 。 对 于 Taco Cloud 应 用 来 
说 ， 我 们 最 初 的 依赖 项 如 图 1.4 所 示 。 


New Spring Starter Project Dependencies (0) 


Spring Boot Version: 2.0.4 





Frequently Used: 


Actuator DevTools Embedded MongoDB 
H2 JPA Lombok 
Rest Repositories Thymeleaf Web 
Available: Selected: 
[rype to search depensencies MM) Deviools 
X Thymeleaf 


Azure X Web 
Cloud AWS 


上 

b Cloud Circuit Breaker 
b Cloud Config 
b Cloud Contract 
b Cloud Core 

b Cloud Discovery 
b Cloud Messaging 
b Cloud Routing 

b Cloud Support 
b Cloud Tracing 

b Core 

» 1/O 

b Integration 

b NoSQL 

b Ops 

» 


pivotal Cloud Fauncrv Make Default Clear Selection 


(9) < Back Next > Cancel 


图 1.4 ”选择 Starter 依 赖 


现在 ， 你 可 以 点 击 Finish 来 生成 项 目 并 将 其 谎 加 到 工作 空间 中 。 但 
是 ， 如 果 你 还 和 想 多 体验 一 些 ， 那 么 可 以 再 次 点 击 Next， 看 一 下 新 Starter 
项 目 同 寻 的 最 后 一 页 ， 如 图 1.5 所 示 。 


New Spring Starter Project (0) 





Site Info 
Base Url http://start.spring.io/starter.zip 
Full Url http://start.spring.io/starter.zip?name=taco-cloud&groupld=sia&artifactld=taco-cloud&version=0.0.1- 


SNAPSHOT&description=Taco+Cloud+Example&packageName=tacos&type=maven- 
project&packaging=jar&javaVersion=1.8&language=java&bootVersion=1.5.4.RELEASE&dependencies=devtools&dependenci 
es=lombok&dependencies=thymeleaf&dependencies=web 


(9) < Back Cancel 
图 1.5 ”指定 备用 的 Initializr 地 址 


默认 情况 下 ， 新 项 目的 同 导 会 调用 Spring Initializr 来 生成 项 目 。 通 
第 情况 下 ， 没 有 必要 履 辣 默认 值 ， 这 也 是 我 们 可 以 在 同 导 的 第 二 页 直接 
点 击 Finish 的 原因 。 但 是 ， 如 采 你 基于 霖 种 原因 托管 了 目 己 的 IPnitializr 殉 
隆 版 本 《可 能 是 本 地 机 器 上 的 副本 或 者 公司 防火 场 内 部 运行 的 目 定义 死 
隆 版 本) ， 那 么 你 可 能 需要 在 点击 Finish 之 前 修改 Base Url 输入 域 ， 使 其 
指向 自己 的 Initializr 实 例 。 


在 点 击 Finish 之 后 ， 项 目 会 从 Initializr 下 载 并 加 载 到 工作 空间 中 。 此 
上 时， 要 等 每 它 加 载 和 构建 ， 然 后 你 就 可 以 开始 开发 应 用 功能 了 。 下 面 我 
们 看 一 下 Initializr 都 为 我 们 提供 了 什么 。 


1.2.2 检查 Spring 项 目的 结构 


项 目 加 载 到 IDE 中 之 后 ， 我 们 将 其 展开 ， 看 一 下 其 中 都 包含 什么 内 
容 。 图 1.6 展 现 了 Spring Tool Suite 中 已 展开 的 Taco Cloud 项 目 。 


上 量 Package Explorer 多 = 一 


YEE5taco-cloud [boot] [devtools] 
Vv (Ssrc/main/java 
Vv 朵 tacos 
| 月 TacoCloudApplication.java 
Vv CS src/main/resources 
(> static 
[templates 
2B application.properties 
Vv (Ssrc/test/java 
Vv 出 tacos 
区 nD TacoCloudApplicationTests.java 
> Bm JRE System Library [JavaSE-1.8] 
p> 到 Maven Dependencies 
> Ey Src 
[target 
=| rmvnw 
pq mvnw.cmd 
Im] pom.xml 


图 1.6 ”Spring Tool Suite 中 所 展现 的 初始 Spring 项 目 结构 


你 可 能 已 经 看 出 来 了 ， 这 束 古 一 个 典型 的 Maven 或 Gradle 项 目 结 
构 ， 其 中 应 用 的 源码 放 到 了 “src/main/java” 中 ， 测 试 代 码 放 到 
了 “src/test/java” 中 ， 而 非 Java 的 资源 放 到 了 “src/main/resources”。 在 这 个 
项 目 结构 中 ， 我 们 家 要 注意 以 下 儿 操 。 


。mvnw 和 mvnw.cmd: 这 是 Maven 包 装 和 (wrapper) 脚本 。 信 助 这 些 


脚本 ， 即 便 你 的 机 右上 没有 安溪 Maven， 也 可 以 构建 项 目 。 

。 pom.xml: 这 是 Maven 构 建 规范 ， 随 后 我 们 将 会 深入 介绍 该 文件 。 

。 TacoCloudApplication.java: 这 是 Spring Boot 主 类 ， 它 会 局 动 该 项 
目 。 随 后 ， 我 们 会 详细 介绍 这 个 类 。 

。 application.properties: 这 个 文件 起 初 是 空 的 ， 但 是 它 为 我 们 提供 了 
指定 配置 属性 的 地 方 。 在 本 章 中 ， 我 们 会 稍微 修改 一 下 这 个 文件 ， 
但 是 我 会 将 配置 属性 的 评 细 阐述 放 到 第 5 章 。 

。 static: 在 这 个 文件 严 下 ， 你 可 以 存放 任意 为 浏 席 需 提 供 服务 的 静态 
内 容 〈 图 片 、 样 式 表 、JavaScript 等 ) ， 该 文件 夹 初 始 为 空 。 

。 templates: 这 个 文件 夹 中 存放 用 来 泻 染 内 容 到 浏 贤 右 的 模板 文件 。 
这 个 文件 夹 初始 是 空 的， 不 过 我 们 很 快 殉 会 往 里 面 添加 Thymeleaf 
模板 。 

。 TacoCloudApplicationTests.java: 这 是 一 个 简单 的 测试 类， 它 能 确保 
Spring 应 用 上 下 文 可 以 成 功 加 载 。 在 开发 应 用 的 过 程 中 ， 我 们 会 将 
更 多 的 测试 添加 进来 。 


随 独 Taco Cloud 应 用 功能 的 增长 ， 我 们 会 不 断 使 用 Java 人 代码、 网 
片 、 样 式 表 、 测 斌 以 及 其 他 附属 内 容 来 充实 这 个 项 目 结构 。 不 过 ， 在 此 
之 前 ， 我 们 先 看 一 下 Spring Initializr 提 供 的 几 个 条 目 。 


探索 爸 建 规范 


在 填 苑 Initializr 表 音 的 时 候 ， 我 们 声明 项 目 要 使 用 Maven 来 进行 构 
建 。 因 此 ，Spring Initializr 所 生成 的 pom.xml 文 件 已 经 包含 了 我 们 所 选择 
的 依赖 。 程 序 清单 1.1 展示 了 Initializr 为 我 们 提供 的 完整 pom.xml。 


程序 清单 1.1 初始 的 Maven 构 建 规 苍 





<?xml] version="1.60" ”encoding= UTF-8 ?> 


<project xmlns="http://maven.apache.org/POM/4.0.0" 
xmlns:xsi="http://www.w3.org/2601/XMLSchema-instance”" 
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
http://maven.apache.org/xsd/maven-4.06.0.xsd"> 
<modelVersion>4.60.6</modelVersion> 


<groupId>sia</groupId> 
<artifactId>taco-cloud</artifactId> 
<version>0.6.1-SNAPSHOT</version> 
<packaging>jar</packaging> 一 --- 打包 为 JAR 


<name>taco-cloud</name> 
<description>Taco Cloud Example</description> 


<parent> 
<grouplId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-parent</artifactId> 


<version>2.6.4.RELEASE</versiony> 一 --- Spring Boot 的 
版 本 
<relativepath/> <!-- lookup parent from repository --> 
</parent> 
<properties> 


<project.build.sourceEncoding> 
UTF-8</project.build.sourceEncoding> 
<project.reporting.outputEncoding> 
UTF-8</project.reporting.outputEncoding> 
<Java.version>1.8</jJava.version> 
</properties> 


<dependencies> 

<dependency> 一 --- Starter 依 赖 
<grFoupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-thymeleaf</artifactId> 

</dependency> 

<dependency> 
<grouplId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-webx</artifactId> 

</dependency> 

<dependency> 
<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-devtools</artifactId> 
<scope>runtime</scope> 

</dependency> 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-test</artifactId> 
<SCOpe>test</scopey> 
</dependencyy> 


<dependency> 
<grouplId>org.seleniumhqg.selenium</groupId> 
<artifactId>selenium-Java</artifactId> 
<SCOpe>test</scopey> 
</dependencyy> 


<dependency> 
<grouplId>org.seleniumhq.selenium</groupId> 
<artifactId>htmlunit-driver</artifactId> 
<SCOpe>test</scopey> 
</dependencyy> 
</dependencies> 
<build> 
<plugins> 
<plugin> 一 --- Spring Boot 插 件 
<grouplId>org.springframework.boot</groupId> 
<artifactId>spring-boot-maven-plugin</artifactId> 
</plugin> 
</plugins> 
</build> 


</project> 


在 pom.xml 文 件 中 ， 我 们 第 一 个 需要 注意 的 地 方 焉 是 <packaging>。 
我 们 选择 了 将 应 用 构建 成 一 个 可 执行 的 JAR 文 件 ， loo di 这 
可 能 是 你 所 做 出 的 最 奇怪 的 选择 之 一 ， 对 Web 应 用 来 说 尤为 如 此 。 
葛 ， 传 统 的 Java Web 应 用 都 是 打包 成 WAR 文 件 ，JAR 只 是 用 来 打 a 
较为 少见 的 梨 面 UI 应 用 的 。 


打包 为 JAR 文 件 是 基于 云 思维 做 出 的 选择 。 尽 管 WAR 文 件 非常 适合 
部 署 到 传统 的 Java 应 用 服务 器 上 ， 但 对 于 大 多 数 云 平台 来 说 它们 并 不 是 
理想 的 选择 。 有 些 云 平台 (比如 Cloud Foundry) 也 能 够 部 署 和 运行 
WAR 文 件 ， 但 是 所 有 的 Java 云 平台 都 能 够 运行 可 执行 的 JAR 文 件 。 因 


此 ，Spring Initializr 默 认 会 使 用 基于 JAR 的 打包 方式 ， 除 非 我 们 明确 告诉 
它 采 用 其 他 的 方式 。 


如 果 你 想 要 将 应 用 部 署 到 传统 的 Java 应 用 服务 器 上 ， 那 么 需要 选择 
使 用 基于 WAR 的 打包 方式 并 要 包含 一 个 Web 初 始 化 类 。 在 第 2 半 中 ， 我 
们 将 会 更 详细 地 了 解 如 何 构 建 WAR 文 件 。 


接 下 来 ， 请 留意 <parent> 元 系 ， 更 具体 来 说 是 它 的 <version> 子 元 
素 。 这 表明 我 们 的 项 目 要 以 Spring-boot-starter-parent 作 为 其 父 POM。 除 
了 其 他 的 一 些 功能 之 外 ， 这 个 父 POM 为 Spring 项 目 间 用 的 一 些 库 提 供 了 
依赖 管理 ， 现 在 你 不 需要 指定 它们 的 古本 ， 因 为 这 古 通 过 父 POM 来 管理 
的 。 这 里 的 2.0.4.RELEASE 表 明 要 使 用 Spring Boot 2.0.4， 所 以 会 根据 这 
个 版 本 的 Spring Boot 定 义 来 继承 依赖 管理 。 


既然 我 们 谈 到 了 依赖 的 话题 ， 那 么 需要 注意 在 <dependencies> 元 系 
下 声明 了 3 个 依赖 。 在 某 种 程度 上 ， 你 可 能 会 对 前 两 个 更 熟悉 一 些 。 它 
们 直接 对 应 我 们 在 Spring Tool Suite 新 项 目 问 导 中 点 击 Finish 之 前 所 选择 
的 Web 和 Thymeleaf 依 赖 。 第 三 个 依赖 提供 了 很 多 有 用 的 测试 功能 。 我 
们 没有 必要 在 专门 的 复 选 框 中 选择 它 ， 因 为 Spring Initializr 假 定 你 将 会 
编写 测试 “和 希望 你 会 正确 地 开展 这 项 工作 ) 。 


你 可 能 也 会 注意 到 这 3 个 依赖 的 artifact ID 上 都 有 starter 这 个 单词 。 
Spring Boot starter 依 赖 的 特别 之 处 在 于 它们 本 号 并 不 包含 库 代 码 ， 而 古 
传递 性 地 拉 取 其 他 的 库 。 这 种 starter 依 赖 主要 有 3 个 好 人 处。 


。 构建 文件 会 显 兰 减 小 并 且 更 易于 管理 ， 因 为 这 样 不 必 为 每 个 所 需 的 


依赖 库 都 声明 依赖 。 

。 我 们 能 够 根据 它们 所 提供 的 功能 来 思考 依赖 ， 而 不 是 根据 库 的 名 
称 。 如 果 是 开 友 Web 应 用 ， 那 么 你 只 需要 添加 web starter 就 可 以 
了 ， 而 不 上 必 添 加 一 扒 单 独 的 库 再 编写 Web 应用。 

。 我 们 不 必 再 担心 库 版 本 的 问题 。 你 可 以 直接 相信 给 定 厂 本 的 Spring 
Boot， 传 递 性 引入 的 库 的 版 本 是 兼容 的 。 现 在 ， 你 只 需要 关心 使 用 
的 是 哪个 版 本 的 Spring Boot 就 可 以 了 。 


最 后 ， 构 建 规范 还 包含 一 个 Spring Boot 插 件 。 这 个 插件 提供 了 一 些 
重要 的 功能 。 


。 它 提供 了 一 个 Maven goal， 人 允许 我 们 使 用 Maven 来 运行 应 用 。 在 
1.3.4 小 节 ， 我 们 将 会 笑 试 这 个 goal。 

它 会 确 你 依赖 的 所 有 库 都 会 包含 在 可 执行 JAR 文 件 中 ， 并 且 能 够 你 
证 它们 在 运行 时 类 路 径 下 十 可 用 的 。 

它 会 在 JAR 中 生成 一 个 manifest 文 件 ， 将 引导 类 【在 我 们 的 场景 

中 ， 也 就 是 TacoCloudApplication ) 声明 为 可 执行 JAR 的 主 类 。 


谈 到 了 主 类 ， 我 们 打开 它 看 一 下 。 


因为 我 们 将 会 通过 可 执行 JAR 文 件 的 形式 来 运行 应 用 ， 所 以 很 重要 
的 一 所 就 是 要 有 一 个 主 类 ， 它 将 会 在 JAR 运 行 的 时 候 饭 执行 。 我 们 同时 
还 需要 一 个 最 小 化 的 Spring 配 置 ， 以 引导 该 应 用 。 这 束 是 
TacoCloudApplication 类 所 做 的 事情 ， 如 程序 清单 1.2 所 未 。 





程序 清单 1.2 ”Taco Cloud 的 引导 类 


package tacos; 


import org.springframework.boot.SpringApplication; 
Import org.springframework.boot.autoconfigure.SpringBootApplication,; 


@SpringBootApplication 一 --- Spring Boot 话 用 
public class TacoCloudApplication { 


public static void main(String[] args) { 
SpringApplication.run(TacoCloudApplication.class, args); 一 --- 运行 
应 用 
} 





立 管 在 TacoCloudApplication 中 只 有 很 少 的 代码 ， 但 是 它 包 含 了 很 多 
的 内 容 。 其 中 ， 最 强大 的 一 行 代码 也 是 最 短 的 。 
@SpringBootApplication 注 解 明确 表明 这 是 一 个 Spring Boot 恬 用。 但是， 
(@SpringBootApplication 远 比 看 上 去 更 强大 。 


@SpringBootApplication 是 一 个 组 合 注解 ， 它 组 合 了 3 个 其 他 的 注 
解 。 


。 @SpringBootConfiguration: 将 访 类 声明 为 配置 茯 。 尽 管 这 个 类 目前 
还 没有 太 多 的 配置 ， 但 是 后 续 我 们 可 以 按 知 瀛 加 基于 Java 的 Spring 
框架 配置 。 这 个 注解 实际 上 古 @Configuration 注 解 的 特殊 形式 。 

。 (DEnableAutoConfiguration: 局 用 Spring Boot 的 自动 配置 。 我 们 随后 
会 介绍 自动 配置 的 更 多 功能 。 束 现在 来 襄 ， 我 们 只 需要 知道 这 个 注 
解 会 告诉 Spring Boot 目 动 配置 它 认 为 我 们 会 用 到 的 组 件 。 

。@ComponentScan: 局 用 组 件 扫 摘 。 这 样 我 们 能 够 通过 像 
@Component、@Controller、@Service 这 样 的 注解 声明 其 他 类 ， 
Spring 会 目 动 友 现 它们 并 将 它们 注册 为 Spring 应 用 上 下 文中 的 组 
作 。 


TacoCloudApplication 夯 外 一 个 很 重要 的 地 方 是 它 的 main(0) 方 法 。 这 
是 JAR 文 件 执行 的 时 候 要 运行 的 方法 。 在 大 多 数 情况 下 ， 这 个 方法 都 是 
样板 代码 ， 我 们 编写 的 每 个 Spring Boot 应 用 都 会 有 一 个 类 似 或 完全 相同 
的 方法 《〈《 关 名 不 同 则 画 当 别论 ) 。 


这 个 main() 方 法 会 调用 SpringApplication 中 静态 的 run0 方 法 ， 后 者 会 
真正 执行 应 用 的 引导 过 程 ， 也 残 是 创建 Spring 的 应 用 上 和 下文。 在 传递 给 
rung0 的 两 个 参数 中 ， 一 个 是 配置 关 ， 夯 一 个 是 命令 行 参 数 。 尽 管 传递 给 
run() 的 配置 类 不 一 定 要 和 引 守 类 相同 ， 但 这 是 最 便利 和 最 典型 的 做 法 。 

你 可 能 并 不 需要 修改 引导 类 中 的 任何 内 容 。 对 于 简单 的 应 用 程序 来 
说 ， 你 可 能 会 及 现在 引导 类 中 配置 一 两 个 组 件 是 非常 方便 的 ， 但 是 对 于 
大 多 数 应 用 来 说 ， 了 最 好 还 是 要 为 没有 实现 自动 配置 的 功能 创建 一 个 单独 
的 配置 类 。 在 本 书 的 整个 过 程 中 ， 我 们 将 会 创建 多 个 配置 类 ， 所 以 请 继 
续 关 注 后 续 的 细节。 


名 弃 应 用 


测试 是 软件 开发 的 重要 组 成 部 分 。 鉴 于 此 ，Spring Initializr 为 我 们 
提供 了 一 个 测试 类 作为 起 步 。 程 序 清早 1.3 展 现 了 这 个 测试 类 的 概况 。 


程序 清单 1.3 ”应 用 测试 类 的 概况 





package tacos; 


import org.jJjunit.Test ; 

import org.jJunit.runner.RunWith; 

Import org.springframework.boot.test.context.SpringBootTest; 
Import org.springframework.test.context.jJunit4.SpringRunner; 


QORunWwWith(SpringRunner .class ) 一 --- 使 用 Spring 
的 运行 项 

QOSpringBootTest 一 --- Spring Boot 测 试 
public class TacoCloudApplicationTests { 


@Test 一 --- 测试 方法 
public void contextLoads() { 
} 





TacoCloudApplicationTests 类 中 的 内 容 并 不 多 : 这 个 类 中 只 有 一 个 
室 的 测试 方法 。 即 便 如 此 ， 这 个 测试 类 还 是 会 执行 必要 的 检 树 ， 确 保 
Spring 应 用 上 下 文 能 够 成 功 加 载 。 如 果 你 所 做 的 变更 导致 Spring 应 用 上 
下 文 无 法 创建 ， 那 么 这 个 测试 将 会 失败 ， 你 束 可 以 做 出 反应 来 解决 相关 
的 问题 了 。 


妨 外 ， 注 意 这 个 类 市 有 @RunWith(SpringRunner.class) 注 解 。 
@RunWith 是 JUnit 的 注 骨 ， 它 会 提供 一 个 测试 运行 磊 runner) 来 指导 
JUnit 如 何 运 行 测 试 。 可 以 将 其 想象 为 给 JUnit 应 用 一 个 插件 ， 以 提供 目 
定义 的 测试 行为 。 在 本 例 中 ， 为 JUnit 提 供 的 是 SpringRunner， 这 是 一 个 
Spring 提供 的 测试 运 行 器 ， 它 会 创建 测试 运行 所 需 的 Spring 必用 上 下 
Be: 


出 试 运 行 右 的 其 他 名 称 


如 末 你 已 经 台 悉 如 何 编 与 Spring 训 试 或 者 见 过 其 他 一 些 基 于 Spring 
的 测试 类 ， 那 么 你 可 能 见 过 名 为 SpringJUnit4ClassRunner 的 测试 运行 
是 。SpringRunner 古 SpringJUnit4ClassRunner 的 别名 ， 和 是 在 Spring 4.3 中 


引入 的 ， 以 便于 移 除 对 特定 JUnit 版 本 的 关联 (比如 ，JUnit 4) 。 有 坚 无 疑 
问 ， 这 个 别名 更 易于 阅读 和 输入 。 


@SpringBootTest 会 告诉 JUnit 在 局 动 测试 的 时 候 要 谎 加 上 Spring 
Boot 的 功能 。 从 现在 开始 ， 我 们 可 以 将 这 个 测试 类 视 同 为 在 main0 方 法 
中 调用 SpringApplication.run0。 在 这 本 书 中 ， 我 们 将 会 多 次 看 到 
@SpringBootTest， 而 且 会 不 断 见识 它 的 威力 。 


最 后 ， 就 是 测试 方法 本 身 了 。 尽 管 @RunWith(SpringRunner.class) 和 
@SpringBootTest 会 为 测试 加 载 Spring 应 用 上 和 下文， 但 是 如 果 没 有 任何 测 
试 方 法 ， 那 么 它们 其 实 什 么 事情 都 没有 做 。 即 便 没 有 任何 断言 或 代码 ， 
这 个 空 的 测试 方法 也 会 提示 这 两 个 注解 完成 了 它们 的 工作 并 成 功 加 载 
Spring 应 用 上 和 下文。 如 采 这 个 过 程 中 有 任何 问题 ， 那 么 测试 都 会 失败 。 


此 时 ， 我 们 已 经 看 完了 Spring Initializr 为 我 们 提供 的 代码 。 我 们 看 
到 了 一 些 用 来 开发 Spring 应 用 程序 的 基础 样板 ， 但 是 还 没有 编写 任何 代 
伺 。 现 在 是 时 候 月 动 IDE、 准 备 好 键盘 并 同 Taco Cloud 应 用 程序 添加 一 
些 自 定义 的 代码 了 。 


1.3 编 与 Spring 心 用 


因为 是 刚刚 开始 ， 所 以 我 们 首先 为 Taco Cloud 做 一 些小 的 变更 ， 但 
征 这 些 变 更 会 展现 Spring 的 很 多 优点 。 在 刚 开 始 的 时 候 ， 比 较 合 适 的 做 
法 是 为 Taco Cloud 应 用 湛 加 一 个 主 足 。 在 洪 加 主页 时 ， 我 们 将 会 创建 两 
Ma 


。 一 个 控制 硕 基 ， 用 来 处 理 主页 相关 的 请 求 
。 一 个 视图 模板 ， 用 来 定义 主页 看 起 来 是 什么 样子 。 


测试 和 是非 钊 重要 的 ， 所 以 我 们 还 会 编 与 一 个 和 商 单 的 名 弃 类 来 负 斌 主 
页 。 但 是 ， 要 事 优 和 匈 ， 我 们 需要 先 编写 控制 秦 。 


1.3.1 处理 Web 请 求 


Spring 目 市 了 一 个 强大 的 Web 框 染 ， 名 为 Spring MVC。Spring MVC 
的 核心 是 控制 右 〈controller) 的 理念 。 控 制 器 是 处 理 请 求 并 以 某 种 方式 
进行 信息 啊 应 的 类 。 在 面 癌 浏览 器 的 应 用 中 ， 控 制 器 会 项 宛 可 选 的 数据 
模型 并 将 请 求 传 违 给 一 个 视图 ， 以 便于 生成 返回 给 浏览 右 的 HTML。 

人 在 第 2 草 中 ， 我 们 将 会 学 习 更 多 天 于 Spring MVC 的 知识 。 现 在 ， 我 
们 会 编写 一 个 简单 的 控制 器 类 以 处 理 对 根 路 径 〈 比 如 ，“”) 的 请 求 ， 并 
将 这 些 请 求 转 友 至 主页 视图 ， 在 这 个 过 程 中 不 会 填 元 任何 的 模型 数据 。 
程序 清单 1.4 展示 了 这 个 简单 的 控制 器 类 。 


程序 清单 1.4 主页 控制 器 





package tacos; 


Import org.springframework.stereotype.Controller.; 
Import org.springframework.web.bind.annotation.GetMapping; 


@Controller 一 --- 控制 右 
public class HomeController { 


@GetMapping("/") 一 --- 处 理 对 根 路 径 “/” 的 请 求 
public String home() { 
return "home"; 一 --- 人 返回 视图 名 


} 


) 


可 以 看 人 到， 这 个 类 各 有 (@Controller。 束 其 本 号 而 言 ，@Controller 并 
没有 做 太 多 的 事情 。 它 的 主要 目的 是 让 组 件 扫 搬 将 这 个 类 识别 为 一 个 组 
件 。 因 为 HomeController 市 有 @Controller， 上 所 以 Spring 的 组 件 扫 摘 功能 
会 自动 发 现 它 ， 并 创建 一 个 HomeController 实 例 作 为 Spring 应 用 上 下 文 
中 的 bean。 


实际 上 ， 有 一 些 其 他 的 注解 与 @Controller 有 着 类 似 的 目的 (包括 
@Component、(@Service 和 (@Repository) 。 你 可 以 为 HomeController 洪 
加 上 述 的 任意 其 他 注解 ， 其 作用 是 完全 相同 的 。 但 是 ， 在 这 里 选择 使 用 
@Controller 更 能 描述 这 个 组 件 在 应 用 中 的 角色 。 


home() 古 一 个 人 简 蛙 的 控制 如 方法 。 它 市 有 @GetMapping 注 和 解 ， 表 明 
如 有 果 针 对 “/” 发 这 HTTP GET 请 求 ， 那 么 这 个 方法 将 会 处 理 请 求 。 访 方法 
所 做 的 只 是 返回 String 类 型 的 home 值 。 


这 个 值 将 会 饭 解 析 为 视图 的 逻辑 名 。 视 图 如 何 实现 取决 于 多 个 因 
系 ， 但 是 因为 Thymeleaf 位 于 类 路 人 径 中 ， 所 以 我 们 可 以 使 用 Thymeleaf 来 
定义 檬 板 。 


为 何 使 用 Thymeleaf 


你 可 能 会 想 为 什么 要 选择 Thymeleaf 作 为 模板 引擎 呢 ? 为 何不 使 用 
JSP? 为 何不 使 用 FreeMarker? 为 何不 选择 其 他 的 几 个 可 选 方案 ? 


简单 来 说 ， 我 必须 要 做 出 选择 ， 我 喜欢 Thymeleaf， 相 对 于 其 他 的 
方案 ， 我 会 优先 使 用 它 。 即 便 JSP 是 更 加 显而易见 的 选择 ， 但 是 组 合 使 
用 JSP 和 Spring Boot 需 要 克服 一 些 挑战 。 我 不 想 脱离 第 1 章 的 内 容 定位 ， 
所 以 在 这 里 就 此 打住 。 在 第 2 章 中 ， 我 们 将 会 看 一 下 其 他 的 模板 方案 ， 
其 中 也 包括 JSP。 


模板 名 称 是 由 逻辑 视图 名 派生 而 来 的 ， 再 加 上 “Vtemplates/”* 朋 级 
和 和“.html” 后 级 。 最 终 形成 的 模板 路 径 将 是 “/templates/home.html”。 所 
以 ， 我 们 需要 将 模板 放 到 项 目 
的 “/Ssrc/mainresources/templates/home.html” 目 孙 中 。 现 在 ， 束 让 我 们 来 
创建 这 个 模板 。 


1.3.2 定义 视图 


为 了 让 主页 尽 可 能 人 简单， 除了 欢迎 用 户 访 问 站 点 之 外 ， 它 不 会 做 其 
他 的 任何 事情 。 程 序 清单 1.5 展 现 了 基本 的 Thymeleaf 模 板 ， 它 定义 了 
Taco Cloud 的 主页 。 


程序 清单 1.5 Taco Cloud 主 页 模板 





<!1DOCTYPE html> 
<html xmlns="http://www.w3.org/1999/xhtml" 
xmlns:th="http://www.thymeleaf.org"> 
<head> 
<title>Taco Cloud</title> 
</head> 


<body> 
<hi>Welcome to...</hi> 
<img th:src="Q@{/images/TacoCloud.png}"/> 


</body> 
</html> 
这 个 模板 并 没有 太 多 需要 讨论 的 。 唯 一 需要 注意 的 一 行 代码 是 用 于 
展现 Taco Cloud Logo 的 <img> 标 签 。 它 使 用 了 Thymeleaf 的 th:src 属 性 和 


@{...} 表 达 式 ， 以 便于 引用 相对 于 上 下 文 路径 的 图 片 。 际 此 之 外 ， 它 刺 
是 一 个 Hello World 页 面 。 


人 和 但是， 我们 再 讨论 一 下 这 个 图 片 。 我 将 定义 Taco Cloud Logo 的 工作 
留 给 你 ， 你 需要 将 它 放 到 应 用 的 正确 位 置 中 。 


图 片 是 使 用 相对 于 上 下 文 的 wimages/TacoCloud.png” 路 径 来 进行 引 
用 的 。 回 忆 一 下 我 们 的 项 目 结构 ， 像 图 斤 这 样 的 衣 态 资源 是 放 
到 “src/mainresources/static” 文 件 夹 中 的 。 这 意味 看， 在 项 目 中 ，Taco 
Cloud Logo 图 搬 必 须要 位 于 “src/main/resources/static/ 


images/TacoCloud.png”。 


我 们 已 经 有 了 一 个 处 理 主页 请 求 的 控制 套 并 且 有 了 演 染 主页 的 模 
板 ， 现 在 基本 就 可 以 局 动 应 用 来 看 一 下 它 的 效果 了 。 在 此 之 前 ， 我 们 先 
看 一 下 如 何 为 控制 右 编 写 测 试 。 


1.3.3 测试 控制 亏 
在 测试 Web 应 用 时 ， 对 HTML 页 面 的 内 容 进 行 断言 是 比较 困难 的 。 


钼 好 Spring 对 测试 提供 了 强大 的 支持 ， 这 使 得 测试 Web 应 用 变 得 非常 倍 
时 


对 于 主页 来 说 ， 我 们 所 编写 的 测试 在 复兴 性 上 与 主页 本 里 到 不 多 。 
测试 需要 针对 根 路 径 “/* 发 送 一 个 HTTP GET 请 求 并 期 望 得 到 成 功 结果 ， 
其 中 视图 名 称 为 home 并 且 结 果 内 容 包 仿 “Welcome to.”。 程 序 清 单 1.6 能 
够 完成 该 任务 。 


程序 清单 1.6 ”针对 主页 控制 右 的 测试 


package tacos; 


Import static org.hamcrest.Matchers.containsString; 

import static 
org.springframework.test.web.servlet.request.MockMvcRequestBuilders.g 

et 七 ; 

import static 
org.springframework.test.web.servlet.result.MockMvcResultMatchers .con 

tent; 

import static 
org.springframework.test.web.servlet.result.MockMvcResultMatchers. sta 

tus,; 

import static 
org.springframework.test.web.servlet.result.MockMvcResultMatchers .vie 

W， 


import org.jJjunit.Test ; 

import org.jJunit.runner.RunWith; 

import org.springframework.beans.factory.annotation.Autowired; 

import org.springframework.boot.test.autoconfigure.web.servlet .WebMvcTest; 
Import org.springframework.test.context.jJunit4.SpringRunner; 

Import org.springframework.test.web.servlet.MockMvc; 


@RunWith(SpringRunner.class) 
@WebMvcTest(HomeController.class) 一 --- 针对 HomeController 的 Web 测试 
public class HomeControllerTest { 


QAutowired 
private MockMvc mockMvc ; 一 --- 注入 MockMvc 
QTest 
public void testHomePage() throws Exception { 
mockMvc .perform(get("/")) 一 --- 发 起 对 “/” 的 GET 


.andExpect(status().isOk()) 一 --- 期 组 得 到 HTTP 286 


.andExpect(view() .name("home")) 一 --- 期 望 得 到 home 视 图 
.andExpect(content().string( 一 --- 期 望 包含 "Welcome to... 


containsString("Welcome to..."))); 





对 于 这 个 测试 ， 我 们 首先 注意 到 的 可 能 吏 是 它 使 用 了 与 
TacoCloudApplicationTests 类 不 同 的 注解 。HomeControllerTest 没 有 使 用 
@SpringBootTest 标 记 ， 而 征 添 加 了 @WebMvcTest 注 解 。 这 古 Spring 
Boot 所 提供 的 一 个 特殊 测试 注解 ， 它 会 让 这 个 测试 在 Spring MVC 应 用 的 
上 下 文中 执行 。 更 具体 来 讲 ， 在 本 例 中 ， 它 会 将 HomeController 注 册 到 | 
Spring MVC 中 ， 这 样 的话 ， 我 们 束 可 以 同 它 发 这 请 求 了 了 。 


@WebMvcTest 同 样 会 为 测试 Spring MVC 应 用 提供 Spring 环境 的 文 
持 。 尽 管 我 们 可 以 局 动 一 个 服务 器 来 进行 测试 ， 但 是 对 于 我 们 的 场景 3 
说 ， 仿 造 一 下 Spring MVC 有 的 运行 机 制 就 可 以 。 测 试 类 被 注入 了 一 个 
MockMvc， 能 够 让 测试 实现 mockup。 


通过 testHomePage0 方 法 ， 我 们 定义 了 针对 主页 想 要 执行 的 测试 。 


它 首 先 使 用 MockMvc 对 象 对 “/”〈 根 路 径 ) 发 起 HITP GET 请 求 。 对 于 这 
个 请 求 ， 我 们 设置 了 如 下 的 预期 : 


。 响应 应 该 具备 HTTP 200 (OK) 状 态 ; 
。 视图 的 效 辑 名 称 应 该 是 home:; 
。 演 染 后 的 视图 应 该 包含 文本 “Welcome to...”。 


如 朱 在 MockMvc 对 象 肥 大 请 求 之 后 ， 这 些 期 望 有 不 满足 的 话 ， 那 么 


这 个 测试 会 失败 。 但 是 ， 我 们 的 控制 番 和 模板 引擎 在 编写 时 部 满足 了 这 
些 预 期 ， 所 以 测试 应 该 能 够 通过 ， 并 且 市 有 成 功 的 图 标 一 一 全 少 能 够 看 
到 一 些 绿色 的 育 景 ， 表 明 测 斌 通过 了 。 





控制 器 已 经 编写 好 了 ， 视 图 模板 也 已 经 创建 完毕 ， 而 且 我 们 还 通过 
了 测试 ， 看 上 去 我 们 已 经 成 功 实现 了 主页 。 尽 管 测试 已 经 通过 了 ， 但 是 
如 果 能 够 在 浏览 器 中 看 到 结果 那 会 更 有 成 就 感 ， 毕 况 这 才 是 Taco Cloud 
的 客户 所 能 看 到 的 效果 。 接 下 来 ， 我 们 构建 应 用 并 运行 它 。 


1.3.4 构建 和 运行 应 用 


束 像 初始 化 Spring 应 用 有 多 种 方式 一 梓 ， 运 行 Spring 应 用 也 有 多 种 
方式 。 如 条 你 愿意 的 话 ， 可 以 翻 到 附录 部 分 ， 以 了 解 运行 Spring Boot 
用 的 一 些 通 用 方式 。 


因为 我 们 选择 了 使 用 Spring Tool Suite 来 初始 化 和 处 理 项 目 ， 所 以 可 
以 倍 助 名 为 Spring Boot Dashboard 的 便捷 功能 来 帮助 我 们 在 IDE 中 运行 应 
用 。Spring Boot Dashboard 的 表现 形式 是 一 个 Tab 标 位 ， 通 首 会 位 于 IDE 
窗口 的 左下 角 附 近 。 几 1.7 展 现 了 一 个 市 有 标注 的 Spring Boot Dashboard 


为 正在 运行 的 应 用 打 
以 debug 模 式 启动 /重启 所 选项 目 开 一 个 Web 浏 览 右 


停止 所 选项 目 
启动 /重启 所 选项 目 为 正在 运行 的 应 用 


ee | 一 4 个 控制 台 


@@ Boot Dashboard 汉 路 好 国人 昌国 加 十 了 == 日 


v ©@ local 





taco-cloud [devtools] [:8080] 


Spring Boot 


项 目的 列表 表明 该 项 目 启用 了 表明 正在 运行 的 应 用 监听 8080 端 口 


Spring Boot DevTools 


图 1.7 ”Spring Boot Dashboard 的 重点 功能 


图 1.7 包 含 了 一 些 最 有 用 的 细 方 ， 但 是 我 不 想 花 太 多 时 间 介 绍 Spring 
Boot Dashboard 文 持 的 所 有 功能 。 对 我 们 来 说 ， 现 在 最 重要 的 事情 是 需 
要 知道 如 何 使 用 它 来 运行 TacoCloud 应 用 。 确 保 taco-cloud 应 用 程序 在 项 
目 列表 中 能 够 显示 出 来 〈 这 是 图 1.7 中 显示 的 唯一 应 用 ) ， 然 后 点 击 启 
动 按 钮 《上方 工具 栏 最 左边 的 按钮 ， 也 驶 是 市 有 绎 色 三 角形 和 红色 正方 
形 的 投 钮 )》 ， 应 用 程序 应 该 瓯 能 立即 局 动 。 


在 应 用 局 动 的 过 程 中 ， la 控制 台 看 到 一 些 Spring ASCII 码 ， 随 
后 会 是 摘 述 应 用 局 动 各 个 步骤 的 日 志 条 目 。 在 控制 全 输出 的 最 后 ， 你 将 
会 看 到 一 和 8080 (http) 启 动 的 日 志 ， 这 意味 着 此 时 
你 可 以 打开 Web 浏 顺 颖 并 导航 至 主页 ， 这 样 就 能 看 到 我 们 的 劳动 成 果 


稍 等 一 下 ! 刚才 说 局 动 Tomcat? 但 是 我 们 是 什么 时 候 将 应 用 部 畦 到 
Tomcat 的 呢 ? 


Spring Boot 必 用 的 习惯 做 法 是 将 所 有 它 需 要 的 东西 都 放 到 一 起 ， 没 
有 必要 将 其 部 普 到 茶 种 应 用 服务 器 中 。 在 这 个 过 程 中 ， 我 们 根本 没有 将 
应 用 部 闭 到 Tomcat 中 ......Tomcat 是 我 们 应 用 的 一 部 分 ! 《在 1.3.6 小 下 ， 
我 会 介绍 Tomcat 是 如 何 成 为 我 们 应 用 的 一 部 分 的 。) 


现在 ， 应 用 已 经 局 动 起 来 了 ， 打 开 Web 浏 宽带 并 访问 
http://localhost:8080 〈 或 者 在 Spring Boot Dashboard 中 点 击 上 方 的 地 球 样 
式 的 控 钮 ， 如 图 1.7 所 示 〉， 你 将 会 看 到 如 图 1.8 所 示 的 界面 。 如 果 你 设 
计 了 目 己 的 Logo 图 厂 ， 那 么 显示 效果 可 能 会 有 所 不 同 。 但 是 ， 与 图 1.8 
相 比 ， 应 该 不 会 有 太 大 的 到 措 。 


O00@ « HH localhost © 由 a 


Welcome to... 





图 1.8 Taco Cloud 主 页 


看 上 去 似乎 并 不 太 类 观 ， 但 这 个 是 一 本 关于 平面 设计 的 书 。 目 前 ， 
略 巡 人 徐 了 项 的 主页 外 观 已 经 足够 了 ， 生 为 我 们 和 学习 Spring 打下 了 一 个 民 好 
的 开 姑 。 


到 现在 为 止 ， 我 一 直 没 有 提 及 DevTools。 在 初始 化 项 目的 时 候 ， 我 
们 将 其 作为 一 个 依赖 泛 加 了 进来 。 在 了 最 终生 成 的 pom.xml 文 件 中 ， 乞 表 
现 为 一 个 依赖 项 。 甚 至 Spring Boot Dashboard 都 显示 项 目 局 用 了 
DevTools。 那 么 ，DevTools 征 什么 ， 所 又 能 为 我 们 做 些 什么 呢 ? 接 下 
来 ， 让 我 们 快速 浏览 一 下 DevTools 最 有 用 有 的 一 些 特性 。 


1.3.5 了解 Spring Boot DevTools 


顾名思义 ，DevTools 为 Spring 开 及 人 员 提 供 了 一 些 便利 的 开 及 期 工 
其 中 包括 : 


、 
/ 


。 代码 变更 后 应 用 会 目 动 重 局 ; 

当面 同 浏览 器 的 资源 (如 模板 、JavaScript、 样 式 表 ) 等 发 生变 化 
时 ， 会 自动 刷新 浏览 规 ; 

。 目 动 茶 用 模板 绥 存 ; 

如 有 果 使 用 H2 数 据 库 的 话 ， 内 置 了 H2 控 制 台 。 


需要 注意 ，DevTools 并 不 是 IDE 插 件 ， 它 也 不 需要 你 使 用 特定 的 
IDE。 在 Spring Tool Suite、IntelliJ IDEA 和 NetBeans 中 ， 它 都 能 很 好 地 运 
行 。 另 外 ， 因 为 它 的 目的 是 仅仅 用 于 开发 ， 所 以 能 够 很 智能 地 在 生产 环 
境 中 把 自己 禁用 掉 。 《我 们 将 会 在 第 19 章 学 习 应 用 部 署 的 时 候 再 讨论 它 
是 如 何 做 到 这 一 点 的 。) 现在 ， 我 们 主要 关注 Spring Boot DevTools 最 有 


用 的 特性 ， 先 从 应 用 的 目 动 重 局 开始 。 
应 用 自动 重启 


如 果 将 DevTools 作 为 项 目的 一 部 分 ， 那 么 你 可 以 看 到 ， 当 对 项 目 中 
的 Java 代 人 码 和 属性 文件 做 出 修改 后 ， 这 些 变 更 稍 后 束 能 发 挥 作用 。 
DevTools 会 监控 变更 ， 当 它 看 到 有 变化 的 时 候 ， 将 会 目 动 重 司 应 用 。 


更 准确 地 说 ， 当 DevTools 运 行 的 时 候 ， 应 用 程序 会 和 & 加 载 到 Java 虚 
拟 机 (Java virtual Machine，JVM) 两 个 独立 的 类 加 载 右 中 。 其 中 一 个 
类 人 加载 右 会 加 载 你 的 Java 代 人 码 、 属 性 文件 以 及 项 目 中 “src/main/”* 跤 任 下 
几乎 所 有 的 内 容 。 这 些 条 目 很 可 能 会 经 钊 及 生变 化 。 另 外 一 个 类 加 载 器 
会 加 载 依赖 的 库 ， 这 些 库 不 太 可 能 经 常 友 生变 化 。 


当 探 测 到 变更 的 时 候 ，DevTools 只 会 重 独 加 载 包 含 项 目 代 码 的 类 加 
载 磊 ， 并 重 司 Spring 的 应 用 上 和 下文 ， 在 这 个 过 程 中 另外 一 个 类 加 载 硕 和 
JVM 会 原封 不 动 。 这 个 宽 略 非常 精细 ， 但 是 它 能 减少 应 用 局 动 的 时 间 。 


这 种 策略 的 一 个 不 足 之 处 就 是 自动 重启 无 法 有 反映 依赖 项 的 变化 。 这 
是 因为 包含 依赖 库 的 类 加 载 器 不 会 自动 重 狐 加 载 。 这 意味 着 每 当 我 们 在 
构建 规范 中 添加 、 变 更 或 移 除 依 赖 的 时 候 ， 为 了 让 变更 生效 ， 我 们 需要 
重新 启动 应 用 。 


浏 抠 春 目 动 刷 新 和 和 共用 使 板 缓存 


驮 认 情 况 下 ， 像 Thymeleaf 和 FreeMarker 这 样 的 模板 方案 在 配置 时 会 


缓存 模板 解析 的 结果 。 这 样 的 话 ， 在 为 每 个 请 求 提供 服务 的 时 候 ， 模 板 
就 不 用 重新 解析 了 。 在 生产 环境 中 ， 这 是 一 种 很 好 的 方式 ， 因 为 它 会 带 
来 一 定 的 性 能 收益 。 


但 是 ， 在 开 友 期 ， 绥 和 存 模 极 束 个 太 好 了。 在 应 用 运行 的 时 候 ， 如 来 
绥 存 借 板 ， 那 么 我 们 刷新 浏 质 磺 吏 无 法 看 到 模板 变更 的 效率 了。 即便 我 
们 对 模板 做 了 修改 ， 在 应 用 重 司 之 前 ， 绥 存 的 模板 依然 会 有 效 。 


DevTools 通 过 蔡 用 所 有 模板 绥 存 解决 了 这 个 问题 。 你 可 以 对 模板 进 
行 任意 数量 的 修改 ， 只 需要 刷新 一 下 浏览 融融 能 看 到 续 


如 有 末 你 像 我 这 样 ， 连 浏 遇 右 的 刷新 按钮 都 懒得 点 ， 那 么 对 代码 做 出 
变更 之 后 ， 马 上 在 浏览 右 中 看 到 结果 束 好 了 。 笠 和 运 的 是 ，DevTools 有 一 
些 特殊 的 功能 可 以 供 我 们 使 用 。 


DevTools 在 运行 的 时 候 ， 它 会 和 你 的 应 用 程序 一 起 ， 同 时 自动 局 动 
一 个 LiveReload 服 务 嚣 。LiveReload 服 务 占 本 里 并 没有 太 大 的 用 处 。 但 
征 ， 当 和 它 与 LiveReload 浏 览 器 插件 结合 起 来 的 时 候 ， 惑 能够 在 和 模板、 网 
片 、 样 式 表 、JavaScript 等 《实际 上 ， 几 乎 涵 兰 为 浏览 硕 提 供 服务 的 所 有 
内 容 ) 发 生变 化 的 时 候 目 动 刷 新 浏览 桥 。 


LiveReload 有 针对 Google Chrome、Safari 和 Firefox 的 浏览 右 插 件 
(要 对 Internet Explorer 和 Edge 粉 丝 说 声 抱 歉 ) 。 请 访问 LiveReload 官 
网 ， 以 了 解 如 何 为 你 的 浏览 器 安装 LiveReload。 


内 置 的 H2 控 制 台 


虽然 我 们 的 项 目 还 没有 使 用 数据 库 ， 但 是 这 种 情况 在 第 3 草 中 就 会 
及 生变 化 。 如 采 你 使 用 H2 数 据 库 进行 开 及 ，DevTools 将 会 目 动 司 用 
H2。 这 样 的 话 ， 我 们 可 以 通过 Web 浏 览 器 进行 访问 。 你 只 需要 让 浏览 器 
访问 http://localhost:8080/h2-console， 就 能 看 到 应 用 所 使 用 的 数据 。 


此 时 ， 我 们 已 经 编写 了 一 个 尽 官 非 第 人 简 持 却 很 完整 的 Spring 应 用 。 
在 本 书 中 ， 我 们 将 会 不 断 扩 展 它 。 现 在 ， 我 们 要 回 过 头 来 看 一 下 都 完成 
了 哪些 工作 以 及 Spring 发 挥 了 什么 作用 。 


1.3.6 ”回顾 一 下 


回想 一 下 我 们 是 怎样 完成 这 一 切 的 。 人 简短 来 说 ， 在 构建 基于 Spring 
的 Taco Cloud 尾 用 的 过 程 中 ， 我 们 执行 了 如 下 步骤 : 


。 使 用 Spring Initializr 创 建 初始 的 项 目 结 构 ; 

。 编号 控制 絮 类 处 理 针 对 主页 的 请 求 ; 

定义 了 一 个 视图 模板 来 渔 染 主页 ; 

编写 了 一 个 徐 音 的 测试 美 来 验证 工作 符合 预期 。 


这 些 步 又 都 非常 简单 二 接 ， 对 吧 ? 除了 初始 化 应 用 的 第 一 个 步骤 之 


外 ， 我 们 所 做 的 每 一 个 操作 都 专注 于 生成 主页 的 目标 。 


- 


实际 上 ， 我 们 所 编写 的 每 行 代码 部 人 致力 于 实现 这 个 目标 。 除 了 Java 
import 语 名 之 外 ， 我 只 能 在 控制 硕 中 找到 两 行 Spring 相关 的 代码 ， 而 在 
视图 模板 中 一 行 Spring 相关 的 代码 都 没有 。 尽 管 测试 茯 的 大 部 分 内 容 都 
使 用 了 Spring 对 训话 的 文 持 ， 但 是 它 在 测 弃 的 上 下 文中 似乎 没有 那么 共 


有 侵入 性 。 


这 是 使 用 Spring 进 行 开 发 的 一 个 午 要 收益 。 你 可 以 只 天 注 满足 应 用 
需求 的 代码 ， 无 须 考虑 如 何 满足 框架 的 需求 。 尺 省 我 们 偶尔 还 是 需要 编 
写 一 些 框 架 特 定 的 代码 ， 但 是 它们 通常 只 占 整 个 代码 库 很 小 的 一 部 分 。 
正如 我 在 前 文 所 述 ，Spring〈 以 及 Spring Boot) 可 以 视 为 感受 不 到 框架 


的 框架 (frameworkless framework) 。 


但 是 这 又 是 如 何 运行 起 来 的 呢 ? Spring 在 幕后 做 了 些 什 么 来 保证 应 
用 的 需求 能 够 得 到 满足 呢 ? 要 理解 Spring 到 底 做 了 些 人 什么， 我 们 首先 来 
看 一 下 构建 规范 。 


在 pom.xml 文 件 中 ， 我 们 声明 了 对 Web 和 Thymeleaf starter 的 依赖 。 
这 两 项 依赖 会 传递 引入 大 量 其 他 的 依赖 ， 包 括 : 


Spring 的 MVC 框 架 ; 
租 入 式 有 的 Tomcat; 
Thymeleaf 和 Thymeleaf 布 局 方言 ; 


它 还 引入 了 Spring Boot 的 目 动 配置 库 。 当 应 用 局 动 的 时 候 ，Spring 
Boot 的 自动 配置 将 会 探测 到 这 些 库 ， 并 目 动 完成 如 下 功能 
。 在 Spring 应 用 上 下 文中 配置 bean 以 司 用 Spring MVC: 
。 在 Spring 应 用 上 下 文中 配置 舱 入 式 的 Tomcat 服 务 


。 配置 Thymeleaf 视 图 解析 占 ， 以 便于 使 用 ei Spring 
MVC 视 图 。 


简 而 言 乙 ， 目 动 配置 功能 完成 了 所 有 的 脏 活 寂 活 ， 让 我 们 能 够 集中 


精力 编写 实现 应 用 功能 的 代码 。 如 果 你 问 我 对 此 的 观点 ， 那 么 我 认为 这 
是 一 个 很 好 的 安排 


我 们 的 Spring 之 旅 才 刚刚 开始 。Taco Cloud 应 用 程序 只 涉及 Spring 上 所 
提供 功能 的 一 小 部 分 。 在 开始 下 一 步 之 前 ， 我 们 先 整 体 了 解 一 下 


Spring， 看 看 在 我 们 的 路 途中 都 会 有 哪些 地 标 。 
1.4 俯 晤 Spring 风景 线 


要 想 了 解 Spring 的 整体 状况 ， 只 需 答 看 完整 版 本 的 Spring Initializr 
Web 表 单 上 的 那 一 堆 复 选 框 列 表 即 可 。 它 列 出 了 100 多 个 可 选 的 依赖 
项 ， 所 以 我 不 会 在 这 里 列 出 所 有 选项 ， 也 不 会 提供 规 图 ， 但 我 或 励 你 去 
看 一 看 。 同 时 ， 在 这 里 我 会 简单 介绍 一 些 重 点 的 项 目 。 
1.4.1 ” Spring 核心 框架 


如 你 所 料 ，Spring 核 心 框架 是 Spring 领 域 中 一 切 的 基础 。 它 提供 了 


核心 容 况 和 依 荐 注入 框 淋 ， 为 外 还 所 供 了 一 些 其 他 香 要 的 特性 。 


其 中 有 一 项 是 Spring MVC， 也 束 是 Spring 的 Web 框 架 。 你 已 经 看 到 
了 如 何 使 用 Spring MVC 来 编写 控制 右 类 以 处 理 Web 请 求 。 但 是 ， 你 还 没 
看 到 的 是 ，Spring MVC 还 能 用 来 创建 REST API， 以 生成 非 HTML 的 输 
出 。 在 第 2 章 中 ， 我 们 将 会 更 深入 地 介绍 Spring MVC， 并 在 第 6 章 重 新 学 
习 如 何 使 用 它 来 创建 REST API。 


Spring 核心 框架 还 提供 了 一 些 对 数据 持久 化 的 基础 文 持 ， 励 其 羡 基 
于 模板 的 JDBC 文 持 。 在 第 3 章 中 ， 你 将 会 看 到 如 何 使 用 JdbcTemplate。 


在 最 新 版 本 的 Spring 中 ， 还 深 加 了 对 反应 式 〈reactive) 风格 编程 的 
支持 ， 其 中 包括 名 为 Spring WebFlux 的 新 反应 式 wWeb 框 架 ， 这 个 框架 大 
量 人 和 借鉴 了 Spring MVC。 在 第 3 部 分 中 ， 我 们 将 会 学 习 Spring 反 应 式 编 程 
模型 ， 并 在 第 11 章 专门 学 习 Spring WebFlux。 


1.4.2 Spring Boot 


我 们 已 经 看 到 了 Spring Boot 市 来 的 很 多 收益 ， 包 括 starter 依 赖 和 目 
动 配置 。 在 本 书 中 ， 我 们 会 尽 可 能 多 地 使 用 Spring Boot， 并 避免 任何 形 
式 的 显 式 配置 ， 除 非 显 式 配置 是 绝对 必要 的 。 除 了 starter 依 赖 和 目 动 配 
置 ，Spring Boot 还 提供 了 大 量 其 他 有 用 的 特性 : 


。 Actuator 能 够 洞察 应 用 运行 时 的 内 部 工作 状况 ， 包 括 指标 、 线 程 
dump 信 息 、 应 用 的 健康 状况 以 及 应 用 可 用 的 环境 属性 ; 

。 均 活 的 环境 属性 规范 

。 在 核心 框架 的 汕 试 辅助 功能 之 上 提供 了 对 测试 的 额外 文 持 。 


除 此 之 外 ，Spring Boot 还 提供 了 一 个 基于 Groovy 脚 本 的 编程 模型 ， 
称 为 Spring Boot 命令 行 接 口 (Command-Line Interface，CLI) 。 使 用 
Spring Boot CLI， 我 们 可 以 将 整个 应 用 程序 编写 为 Groovy 脚 本 的 集合 ， 
并 通过 命令 行 运行 它们 。 我 们 不 会 伦 太 多 时 间 介 绍 Spring Boot CLI， 但 
古 当 它 罗 配 我 们 的 需求 时 ， 我 们 会 偶尔 提 太 它 。 


Spring Boot 已 经 成 为 Spring 开 肥 中 不 可 或 缺 的 一 部 分 ， 很 难 想象 如 
果 没 有 有 它 我 该 如 何 开 发 Spring 应 用 程序 。 因 此 ， 本 书 米 用 以 Spring Boot 
为 核心 的 视角 。 当 我 介绍 Spring Boot 所 做 的 事情 时 ， 你 可 能 会 发 现 我 却 
使 用 了 Spring 这 个 词 。 


1.4.3 Spring Data 


尺 害 Spring 核 心 框 染 提供 了 基本 有 的 数据 持久 化 支持 ， 但 是 Spring 
Data 提 供 了 非常 令 人 惊叹 的 功能 将 应 用 程序 的 数据 repository 定 义 为 徐 
单 的 Java 接 口 ， 在 定义 驱动 存 伴 和 检索 数据 的 方法 时 使 用 一 种 命名 约定 
BJ。 


此 外 ，Spring Data 能 够 处 理 多 种 不 同类 型 的 数据 库 ， 包 括 关 系 型 数 
据 库 (JPA) 、 文 档 数据 库 (Mongo) 、 图 数据 库 (Neo4j ) 等 。 在 第 3 
章 中 ， 我 们 将 使 用 Spring Data 为 Taco Cloud 应 用 程序 创建 repository。 


1.4.4 Spring Security 


应 用 程序 的 安全 性 一 直 是 一 个 重要 的 话题 ， 而 且 正 在 变 得 越 来 越 重 
。 侠 运 的 是 ，Spring 有 一 个 健壮 的 安全 框架 ， 名 为 Spring Security。 


) 刘 


Spring Security 解 决 了 应 用 程序 通用 的 安全 性 需求 ， 包 括号 份 验 
证 、 授 权 和 API 安 全 性 。Spring Security 的 范围 太 大 ， 在 本 书 中 无 法 得 到 
充分 的 介绍 ， 但 是 我 们 将 在 第 4 章 和 第 11 章 中 讨论 一 些 利 见 的 使 用 场 


1.4.5 Spring Integration 和 Spring Batch 


从 一 定 程 度 上 来 讲 ， 大 多 数 应 用 程序 都 需要 与 其 他 应 用 甚至 本 应 用 
中 的 其 他 组 件 进 行 集成 。 在 这 方面 ， 有 有 一些 应 用 程序 集成 模式 可 以 解决 
这 些 需 求 。Spring Integration 和 Spring Batch 为 基于 Spring 的 应 用 程序 提 
供 了 这 些 模式 的 实现 。 


Spring Integration 解 决 了 实时 集成 问题 。 在 实时 集成 中 ， 数 据 在 可 
用 时 马上 就 会 得 到 处 理 。 相 反 ，Spring Batch 解 决 的 则 是 批 处 理 集成 的 
问题 ， 在 此 过 程 中 ， 数 据 可 以 收集 一 段 时 间 ， 直 到 某 个 触 肥 右 〈 可 能 是 
一 个 时 间 触 发 颖 发 出 信和 号， 表示 该 处 理 批量 数据 了 才 会 对 数据 进行 批 
处 理 。 我 们 将 会 在 第 9 章 中 研究 Spring Batch 和 Spring Integration。 


1.4.6 Spring Cloud 


在 手 与 本 书 的 时 候 ， 应 用 程序 开 友 领域 正在 进入 一 个 新 的 时 代 ， 我 
们 不 再 将 应 用 程序 作为 单个 部 普 单 元 来 开 肥 ， 而 是 使 用 由 微服 务 组 成 的 
多 个 独立 部 普 单 元 来 组 合 形成 应 用 程序 。 


微服 务 是 一 个 热门 话题 ， 解 决 了 开 及 期 和 运行 期 的 一 些 实 际 问 题 。 
然而 ， 在 这 样 做 的 过 程 中 ， 它 们 也 面临 着 自己 所 带 来 的 挑战 。 这 些 挑战 
将 由 Spring Cloud 下 面 解 决 ，Spring Cloud 是 使 用 Spring 开 发 云 原 生 应 用 


程序 的 一 组 项 目 。 


Spring Cloud 敌 凋 了 很 多 领域 ， 本 书 不 可 能 面面俱到 ， 我 们 将 在 第 
13 一 15 章 中 研究 Spring Cloud 的 一 些 常 见 组 件 。 要 更 全 面 地 研究 Spring 
Cloud， 我 建议 阅读 John Carnell 的 Spring Microservices in Action 一 书 呈 

(Manning, 2017) 。 


1.5 小 结 


。 Spring 上 引 在 答 化 开发 人 员 上 所 面临 的 挑战 ， 比 如 创建 Web 应 用 程序 、 
处 理 数据 库 、 体 护 应 用 程序 以 及 实现 微服 务 。 

。 Spring Boot 构 建 在 Spring 之 上 ， 通 过 简化 依赖 管理 、 上 自动 配置 和 运 
行 时 洞察 ， 使 Spring 更 加 易 用 。 

。 Spring 应 用 程序 可 以 使 用 Spring Initializr 进 行 初始 化 。Spring 
Initializr 古 基于 Web 的 应 用 ， 并 且 为 大 多 数 Java 开 友 坏 境 提 供 了 原生 
文 持 。 

。 在 Spring 应 用 上 下 文中 ， 组 件 《〈 通 钊 称 为 bean) 既 可 以 使 用 Java 或 
XML 显 式 声明 ， 也 可 以 通过 组 件 扫 摘 发现， 还 可 以 使 用 Spring Boot 
目 动 配置 功能 实现 目 动 化 配置 。 





[1] 为 了 行文 简洁 ， 同 时 保持 与 示例 应 用 中 Web 页 面 展 现 的 一 致 性 ， 我 
们 后 文 不 再 将 taco 翻 译 为 墨西哥 大 玉米 和 益 ， 而 是 直接 使 用 taco 这 一 叫 
法 。 一 一 译 者 注 


[2] 该 书 中 文 版 《Spring 铀 服务 实战 》 己 由 人 民 邮 电 出 版 社 出 版 
(ISBN978-7-115-48118-4) 。 


第 2 革 ”开发 Web 应 用 


。 在 浏 宽带 中 展现 模型 数据 


。 处 理 和 校 验 表 单 输入 


。 选择 视图 模板 库 





第 一 印象 是 非常 重要 的 : Curb Appeal 能 够 在 购房 者 真正 进门 之 前 束 
将 房子 买 挥 ; 如 果 一 辆 车 咀 成 了 楼 桃色 ， 那 么 它 的 油漆 会 比 它 的 引擎 更 
引 人 注 目 ; 文学 作 癌 中 充满 了 一 见 钟情 的 故事 。 内 在 固然 非 常 重要 ， 但 
征 外 和 在 的 ， 也 吏 是 第 一 眼看 到 的 东西 同样 非常 重要 。 

我 们 使 用 Spring 所 构建 的 应 用 能 完成 各 种 各 样 的 事情 ， 包 括 处 理 数 
据 、 从 数据 库 中 读 取 信息 以 及 与 其 他 应 用 进行 交互 。 但 是 ， 用 户 对 应 用 
程序 的 第 一 印象 来 源 于 用 户 寞 面 。 在 很 多 应 用 中 ，UI 是 以 浏览 右 中 的 
Web 应 用 的 形式 来 展现 的 。 


在 第 1 草 中 ， 我 们 创建 了 第 一 个 Spring MVC 控 制 器 来 展现 应 用 的 主 


页 。 但 是 ，Spring MVC 能 做 很 多 的 事情 ， 并 不 局 限于 展现 静态 内 容 。 在 
本 和 草 中 ， 我 们 将 会 开 肥 Taco Cloud 的 第 一 个 主要 功能 : 设计 定制 taco 的 
能 力 。 在 这 个 过 程 中 ， 我 们 将 会 深入 研究 Spring MVC 并 会 看 到 如 何 展现 
模型 数据 和 处 理 表 单 输入 。 


2.1 展现 信息 


从 根本 上 来 讲 ，Taco Cloud 是 一 个 可 以 在 线 订 购 taco 的 地 方 。 但 
是 ， 除 此 之 外 ，Taco Cloud 人 允许 客户 展现 其 创 晶 ， 能 够 让 他 们 通过 丰 宙 
的 配料 〈ingredient) 设计 目 己 的 taco。 


因此 ，Taco Cloud 需 要 有 一 个 页 面 为 taco 艺 术 家 展现 都 可 以 选择 哪 
些 配 料 。 可 选 的 配料 可 能 随时 会 发 生变 化 ， 所 以 不 能 将 它们 便 编码 到 
HTML 页面 中 。 我 们 应 该 从 数据 库 中 获取 可 用 的 配料 并 将 其 传递 给 页 
面 ， 进 而 展现 给 客户 。 

在 Spring Web 应 用 中 ， 获 取 和 处 理 数 据 是 控制 右 的 任务 ， 而 将 数据 
演 染 到 HTML 中 并 在 浏览 如 中 展现 则 是 视图 的 任务 。 为 了 支撑 taco 的 创 
建 页 面 ， 我 们 需要 构建 如 下 组 件 。 

。 用 来 定义 taco 配 料 属 性 的 领域 类 。 


。 用 来 获取 配料 信息 并 将 其 传 圳 至 视图 的 Spring MVC 控 制 如 类 。 
。 用 来 在 用 户 的 浏 顺带 中 渔 染 配料 列表 的 视图 模板 。 


这 些 组 件 之 间 的 关系 如 图 2.1 所 示 。 


二、 设计 taco 
请 求 的 控制 器 





Web 浏 览 器 


ee 
HTML 


设计 视图 





图 2.1 典型 的 Spring MVC 请 求 流 
因为 本 章 主 要 关注 Spring 虹 Web 框架， 所 以 我 们 会 将 数据 库 相 关 的 
内 容 放 到 第 3 章 中 进行 讲解 。 现 在 的 控制 右 只 负责 回 视 图 提供 配料 。 在 
第 3 曹 中， 我们 会 重新 改造 这 个 控制 器 ， 让 和 它 能 够 与 repository 协 作 ， 从 
数据 库 中 获取 配料 数据 。 
在 编写 控制 项 和 视 岁 之 前 ， 我 们 首先 确定 一 下 用 来 表示 配料 的 领域 
茯 型 ， 它 会 为 我 们 开 有 Web 组件 更 定 基 础 。 


2.1.1 构建 领域 尖 


应 用 的 领域 指 的 是 它 所 要 解决 的 主题 范围 : 也 就 是 会 影 啊 到 对 应 用 
理解 的 理念 和 概念 tH 内。 在 Tao Cloud 应 用 中 ， 领 域 对 象 包括 taco 设 计 、 组 


成 这 些 设计 的 配料 、 顾 客 以 及 顾客 所 下 的 订单 。 作 为 开始 ， 我 们 首先 关 
注 taco 的 配料 . 


在 我 们 的 领域 中 ， Re 每 种 配料 都 有 一 个 
名 称 和 闫 型， 以 便于 对 其 进行 可 视 化 的 分 类 《 筷 日 质 、 奶 酷 、 咨 计 

RE 这 样 的 话 对 它 的 引用 束 能 非常 容易 和 明 
硝 。 如 下 的 mgredient 关 定义 了 我 们 所 需 的 领域 对 象 。 


程序 清单 2.1 定义 taco 配 料 


package 七 acoSs ; 


Import lombok.Data; 
Import lombok.RequiredArgsConstructor; 


@Data 
QRequiredArgsConstructor 
public class Ingredient 1{ 


private final String id; 
private final String name; 
private final Type type; 


public static enum Type 1{ 
WRAP, PROTEIN, VEGGIES, CHEESE, SAUCE 


} 





我 们 可 以 看 到 ， 这 十 一 个 非常 普通 的 Java 领 域 关 ， 它 定义 了 摘 述 配 
料 所 需 的 3 个 属性 。 在 程序 清单 2.1 中 ， a \ 寻 第 的 一 点 是 它 
似乎 缺少 了 常见 有 的 getter 和 setter 方 法 ， 以 及 equals()、hashCode()、 
toString() 等 方法 。 


在 程序 清早 2.1 中 没有 这 些 方法 ， 部 分 原因 古市 省 空间 ， 此 外 还 因 


为 我 们 使 用 了 名 为 Lombok 的 库 〈 这 是 一 个 非常 棒 的 库 ， 它 能 够 在 运行 
时 动态 生成 这 些 方法 ) 。 实 际 上 ， 类 级 别 的 @Data 注 解 束 是 由 Lombok 提 
供 的 ， 它 会 告诉 Lombok 生 成 所 有 缺失 的 方法 ， 同 时 还 会 生成 所 有 以 
final 属 性 作为 参数 的 构造 莫 。 通 过 使 用 Lombok， 我 们 能 够 让 Ingredient 
的 代码 人 简洁 明了 。 


Lombok 并 不 是 Spring 库 ， 但 征 它 非常 有 用 ， 我 及 现 如 条 没有 它 ， 开 
肥 工 作 将 很 难 开 展 。 当 我 需要 在 书 中 将 代码 示例 编写 得 短小 简洁 时 ， 它 
简 卫 成 了 我 的 救星 。 


要 使 用 Lombok， 上 自 先 要 将 其 作为 依赖 洪 加 a 到 项 目 中 。 如 果 你 使 用 
Spring Tool Suite， 那 么 只 需要 用 右键 点 击 pom.xml， 并 从 Spring 上 下 文 
玉昌 选项 中 选择 “Edit Starters”。 在 第 1 章 中 看 到 的 选择 依赖 的 对 话 框 将 
会 再 次 出 现 〈 见 图 1.4) ， 这 样 的 话 我 们 残 有 机 会 添加 依赖 或 修改 己 选 
择 的 依赖 了 。 找 到 Lombok 人 选项 ， 并 确保 它 处 于 已 选中 的 状态 ， 然 后 点 
击 “OK”，Spring Tool Suite 会 自动 将 其 添加 到 构建 规范 中 。 


为 外 ， 你 也 可 以 在 pom.xml 中 通过 如 下 条 目 进行 手动 添加 : 


<dependency> 
<groupId>org.projectlombok</groupId> 


<artifactId>lombok</artifactId> 
<optional>true</optional> 
</dependency> 





这 个 依赖 将 会 在 开发 阶段 为 你 提供 Lombok 注 解 〈 例 如 @Data) ， 并 
且 会 在 运行 时 进行 自动 化 的 方法 生成 。 但 是 ， 我 们 还 需要 将 Lombok 作 
为 扩展 添加 到 IDE 上 ， 人 否则 IDE 将 会 报错 ， 提 示 缺 少 方法 和 final 属 性 没有 


赋值 。 参 见 Lombok 项 目 页 面 ， 以 得 疝 如 何在 你 所 选择 的 IDE 上 安装 
Lombok。 


我 相信 你 会 发 现 Lombok 非 常 有 用 ， 但 你 也 要 知道 ， 它 是 可 选 的 。 
在 开发 Spring 应 用 的 时 候 ， 它 并 不 是 必 备 的 ， 所 以 如 果 你 不 想 使 用 它 的 
话 ， 完 全 可 以 手动 编写 这 些 缺 失 的 方法 。 当 你 完成 之 后 ， 我 们 将 会 在 应 
用 中 添加 一 些 控制 器 ， 让 它们 来 处 理 Web 请 求 。 


2.1.2 ”创建 控制 磺 次 


在 Spring MVC 框 架 中 ， 控 制 右 是 重要 的 参与 者 。 它 们 的 主要 职责 是 
处 理 HTTP 请 求 ， 要 么 将 请 求 传递 给 视图 以 便于 渔 染 HTML〔 浏 贤 器 展 
现 ) ， 要 么 直接 将 数据 写 入 啊 应 体 (RESTful) 。 在 本 章 中 ， 我 们 将 会 
关注 使 用 视图 来 为 Web 浏 览 夯 生成 内 容 的 控制 器 。 在 第 6 草 中 ， 我 们 将 
会 看 到 如 何以 REST API 的 形式 编写 控制 器 来 处 理 请 求 。 


对 于 Taco Cloud 应 用 来 说 ， 我 们 再 要 一 个 简单 的 控制 器 ， 它 要 完成 
如 下 功能 。 


。 处 理 路 径 为 “/design” 的 HTTP GET 请 求 。 

。 构建 配料 的 列表 。 

。 处 理 请 求 ， 并 将 配料 数据 传递 给 要 泻 染 为 HTML 的 视图 模板 ， 故 运 
给 友 起 请 求 的 Web 浏 只 器 。 


程序 清单 2.2 中 的 DesignTacoController 类 解决 了 这 些 需求 。 


程序 清单 2.2 ”初始 的 Spring 控 制 占 类 


package tacos .Web ; 


Import JjJava.util.Arrays; 
import JjJava.util.List,; 
import Java.util.stream.Collectors; 


import Javax.validation.Valid; 


Import org.springframework.stereotype.Controller.; 

Import org.springframework.ui.Model; 

Import org.springframework.validation.Errors; 

Import org.springframework.web.bind.annotation.GetMapping; 
Import org.springframework.web.bind.annotation.PostMapping; 
import org.springframework.web.bind.annotation.RequestMapping; 


import lombok.extern.slf4]j.Sl1f4]; 
import tacos.Taco; 

import tacos.Ingredient,; 

Import tacos.Ingredient.Type; 


@S1f4] 

@Controller 
@QRequestMapping("/design") 

public class DesignTacoController { 


Q@QGetMapping 
public String showDesignForm(Model model) { 
List<Ingredient> ingredients = Arrays.asList( 

new Ingredient("FLTO", "Flour Tortilla", Type.WRAP), 
new Ingredient("COTO", "Corn Tortilla", Type.WRAP), 
new Ingredient("GRBF", "Ground Beef", Type.PROTEIN), 
new Ingredient("CARN", "Carnitas", Type.PROTEIN), 
new Ingredient("TMTO", "Diced Tomatoes", Type.VEGGIES), 
new Ingredient("LETC", "Lettuce", Type.VEGGIES), 
new Ingredient("CHED", "Cheddar", Type.CHEESE), 
new Ingredient("JACK", "Monterrey Jack", Type.CHEESE)., 
new Ingredient("SLSA", "Salsa", Type.SAUCE), 
new Ingredient("SRCR", "Sour Cream", Type.SAUCE) 


/3 


Type[ ] types = Ingredient.Type.values(); 
for (Type type : types) { 
model1.addAttribute(type.toSstring() .toLowerCase( )， 
filterByType(ingredients, type)); 
} 


model.addAttribute("design", new Taco() ) ; 


return "design"; 
} 
private List<Ingredient> filterByType( 
<Ingredient> ingredients, Type type) { 
return ingredients 
.Stream() 
.filter(x -> x.getType().equals(type)) 
.Collect(Collectors.toList()); 





对 于 DesignTacoController， 我 们 先 要 注意 在 类 RN 用 的 注解 。 
自 完 是 @Slf4j， 这 古 Lombok 所 提供 的 注解 ， 在 运行 时 ， 它 会 在 这 个 类 
中 日 动 生成 一 个 SLF4J (Simple Logging Facade for Java) Logger。 这 个 
简 持 的 注解 和 在 类 中 通过 如 下 代码 显 式 声 明 的 效果 是 一 样 的 : 


private static final org.slf4]j.Logger log = 


org.slf4j.LoggerFactory.getLogger(DesignTacoController.class); 





随后 ， 我 们 将 会 用 到 这 个 Logger。 


Doin ontroller 用 到 的 下 一 个 注解 是 @Controller。 这 个 注解 会 
将 这 个 类 识别 为 控制 器 ， 并 且 将 其 作为 组 件 扫 摘 的 候选 者 ， 所 以 Spring 
会 友 现 它 日 动 创建 一 个 DesignTacoController 实 例 ， 并 将 该 实例 作为 
Spring 应 用 上 下 文中 的 bean。 


DesignTacoController 还 市 有 @RequestMapping 注 艇 。 当 
@ReduestMapping 注 解 用 到 美 级别 的 时 候 ， 它 能 够 指定 访 控 制 基 所 处 理 
的 请 求 类 型 。 在 本 例 中 ， 它 规定 DesignTacoController 将 会 处 理 路 径 
以 “design” 开 头 的 请 求 。 


处 理 GET 请 求 


修饰 showDesignForm0 方 法 的 @GetMapping 注 和 解 对 类 级 别 的 
(@RequestMapping 进 行 了 细 化 。@GetMapping 结 合 类 级 别 的 
@RequestMapping， 指 明 当 接收 到 对 “/design” 的 HTTP GET 请 求 时 ， 将 
会 调用 showDesignForm() 来 处 理 请 求 。 


@GetMapping 是 一 个 相对 较 新 的 注解 ， 是 在 Spring 4.3 引 入 的 。 在 
Spring 4.3 之 前 ， 你 可 能 需要 使 用 方法 级 别 的 @RequestMapping 注 解 作为 
蕉 代 : 


显然 ，@GetMapping 蝎 加 简洁 ， 并 且 指 明了 它 的 目标 HTTP 方 法 。 
@GetMapping 只 是 诸多 请 求 映 射 注 解 中 的 一 个 。 表 2.1 列 出 了 Spring 
MVC 中 所 有 可 用 的 请 求 映 射 注解 。 


表 2.1 ” Spring MVC 的 请 求 映 射 注 解 


@RequestMapping 通用 的 请 求 处 理 


@GetMapping 处 理 HTTP GET 请 求 
@PostMapping 处 理 HTTP POST 请 求 





@PutMapping 处 理 HTTP PUT 请 求 


@DeleteMapping 处 理 HTTP DELETE 请 求 
@PatchMapping 处 理 HITP PATCH 请 求 


让 正确 的 事情 变 得 更 容易 


在 为 控制 器 方法 声明 请 求 映 射 时 ， 越 具体 越 好 。 这 意味 着 至 
少 要 声明 路 径 《〈 或 者 从 类 级 别 的 @RequestMapping 继 承 一 个 路 
径 ) 以 及 它 所 处 理 的 HTTP 方 法 。 


但 是 更 长 的 @RequestMapping(method=RequestMethod.GET) 
注解 很 容易 让 开 及 人 员 采 取 懒 惰 的 方式 ， 也 允 是 忽略 挥 method 属 
性 。 圣 亏 有 了 Spring 4.3 的 新 注解 ， 正 确 的 事情 变 得 更 容易 了 ， 
我 们 的 输入 变 得 更 少 了 。 


新 的 请 求 映 射 注解 具有 和 人 @RequestMapping 完 全 相同 的 属 
性 ， 所 以 我 们 可 以 在 使 用 @RequestMapping 的 任何 地 方 使 用 它 
们 ] 。 


通 钟 ， 我 辟 欢 只 在 其 级 别 上 使 用 @RequestMapping， 以 便于 
指定 基本 路 径 。 在 每 个 处 理 吉 方法 上 ， 我 会 使 用 更 具体 的 
@GetMapping、(@PostMapping 等 注解 。 





现在 ， 我 们 已 经 知道 showDesignForm() 方 法 会 处 理 请 求 ， 接 下 来 我 
们 看 一 下 方法 体 ， 看 它 都 做 了 些 什 么 工作 。 这 个 方法 构建 了 一 个 
Ingredient 对 象 的 列表 。 现 在 ， 这 个 列表 是 便 编 码 的 。 当 我 们 学 习 第 3 草 
的 时 候 ， 会 从 数据 库 中 获取 可 用 taco 配 料 并 将 其 放 到 列表 中 。 


配料 列表 准备 就 绪 之 后 ，showDesignForm() 方 法 接 下 来 的 几 行 代码 
会 根据 配料 类 型 过 小 列表 。 配 料 类 型 的 列表 会 作为 属性 添加 a 到 Model 对 
象 上 ， 这 个 对 象 是 以 参数 的 形式 传递 给 showDesignForm() 方 法 的 。 
Model 对 象 负 责 在 控制 右 和 展现 数据 的 视图 之 间 传 递 数 据 。 实 际 上 ， 放 
到 Model 属 性 中 的 数据 将 会 复制 到 Servlet Response 的 属性 中 ， 这 样 视图 
束 能 在 这 里 找到 它们 了 。showDesignForm() 方 法 最 后 返回 “design”， 这 
是 视图 的 逻辑 名 称 ， 会 用 来 将 模型 渔 染 到 视图 上 。 


我 们 的 DesignTacoController 己 经 具备 锥 形 了。 如 果 你 现在 运行 应 用 
并 在 浏览 右上 访问 “design” 路 径 ，DesignTacoController 的 
showDesignForm(O 将 会 被 调用 ， 它 会 从 repository 中 获取 数据 并 放 到 柑 型 
中 ， 然 后 将 请 求 传递 给 和 视图。 但是， 我 们 现在 还 没有 定义 视图 ， 请 求 将 
会 遇 到 很 糟糕 的 问题 ， 也 就 是 HTTP 404 (Not Found) 。 为 了 解决 这 个 
问题 ， 我 们 将 注意 力 切 换 到 视图 上 ， 在 这 里 数据 将 会 使 用 HTML 进 行 装 
饰 ， 以 便于 在 用 户 的 Web 浏 览 嚣 中 进行 展现 。 


2.1.3 ”设计 秽 图 


在 控制 占 完 成 它 的 工作 之 后 ， 现 在 束 访 视图 登场 了 。Spring 提 供 了 


多 种 定义 视图 的 方式 ， 包 括 JavaServer Pages (JSP) 、Thymeleaf、 
FreeMarker、Mustache 和 基于 Groovy 的 模板 。 束 现在 来 讲 ， 我 们 会 使 用 
Thymeleaf， 这 也 是 我 们 在 第 1 章 开 局 这 个 项 目 时 的 选择 。 我 们 会 在 第 2.5 
六 考虑 其 他 的 可 选 方 条 。 


为 了 使 用 Thymeleaf， 我 们 需要 添加 另外 一 个 依赖 到 项 目 构建 中 。 


如 下 的 <dependency> 条 目 使 用 了 Spring Boot 的 Thymeleaf starter， 从 而 能 
够 让 Thymeleaf 泻 染 我 们 将 要 创建 的 视 网 : 


<dependencyy> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-thymeleaf</artifactId> 
</dependency> 





在 运行 时 ，Spring Boot 的 目 动 配置 功能 会 发 现 Thymeleaf 在 类 路 人 竹 
中 ， 因 此 会 为 Spring MVC 创 建文 撑 Thymeleaf 钢 图 的 bean。 


像 Thymeleaf 这 样 的 视图 库 在 设计 时 是 与 特定 的 Web 框 架 解 古 的 。 
这 样 的 话 ， 它 们 无 法 感知 Spring 的 模型 抽象 ， 因 此 无 法 与 控制 器 放 到 
Model 中 的 数据 协同 工作 。 但 是 ， 它 们 可 以 与 Servlet 的 request 属 性 协 
作 。 所 以 ， 在 Spring 将 请 求 转 移 到 视图 之 前 ， 它 会 把 模型 数据 复制 到 
request 属 性 中 ，Thymeleaf 和 其 他 的 视图 模板 方案 就 能 访问 到 它们 了 。 


Thymeleaf 模 板 束 是 增加 一 些 额 外 元 系 属性 的 HTML， 这 些 属性 能 够 
指导 模板 如 何 演 染 request 数 据 。 举 例 来 说， 如 有 果 有 一 个 请 求 属性 的 key 
为 “message”， 我 们 想 要 使 用 Thymeleaf 将 其 泻 染 到 一 个 HTML <p> 标 签 
中 ， 那 么 在 Thymeleaf 借 板 中 我 们 可 以 这 样 与 : 


<p th:text="${message}">placeholder message</p> 


当 模 板 多 染 成 HIMEL 的 时 候 ，<p> 元 系 体 将 会 被 人 将 换 为 Servlet 
Request 中 key 为 “message” 的 属性 值 。“th:text* 是 Thymeleaf 命 名 空间 中 的 
属性 ， 它 会 执行 这 个 伏 换 过 程 。${} 会 告诉 它 要 使 用 某 个 请 求 属性 在 
本 例 中 ， 也 就 是 “message”) 中 的 值 。 


Thymeleaf 还 提供 了 一 个 属性 “th:each”， 它 会 碗 代 一 个 元 素 集 合 ， 大 
集合 中 的 每 个 条 目 泻 染 HTML。 在 我 们 设计 视图 展现 模型 中 的 配料 列表 
时 ， 这 束 非 党 便利 了 。 举 例 来 说 ， 如 果 只 想 演 染 “wrap” 配 料 的 列表 ， 我 
们 可 以 使 用 如 下 的 HIML 户 段 : 


<h3>Designate your wrap:</h3> 
<div th:each="ingredient : ${wrap}"> 


<input name="ingredients" type="checkbox" th:value="${ingredient.id}" /> 
<Span th:text="${ingredient.name}">INGREDIENT</span><br/> 
</div> 





在 这 里 ， 我 们 在 <div> 标 签 中 使 用 th:each 属 性 ， 这 样 的 话 束 能 针对 
wrap request 属 性 所 对 应 集合 中 的 每 个 元 素 重 复 广 染 <div> 了 。 在 每 次 碗 
代 的 时 候 ， 配 料 元 系 都 会 绑 定 到 一 个 名 为 ingredient 的 Thymeleaf 变 量 
es 


在 <div> 元 素 中 ， 有 一 个 <input> 复 选 框 元 兹 ， 还 有 一 个 为 复 选 框 提 
供 标签 的 <span> 元 系 。 复 选 框 使 用 Thymeleaf 的 th:value 来 为 演 染 出 的 
<input> 元 系 设 置 value 属 性 ， 这 里 会 将 其 设置 为 所 找到 的 ingredient 的 id 属 
性 。<span> 元 素 使 用 th:text 将 “INGREDIENT2” 占 位 符 文本 替换 为 
ingredient 的 name 属 性 。 


当 用 实际 的 模型 数据 进行 演 染 的 时 候 ， 其 中 一 个 <div> 迭 代 的 演 染 
结果 可 能 会 如 下 所 示 : 


<div> 
<input name="ingredients" type="checkbox”" value="FLTO" /> 


<span>Flour Tortilla</span><br/> 
</div> 





最 终 ， 上 述 的 Thymeleaf 卢 段 会 成 为 一 大 段 HIML 表 单 的 一 部 分 ， 我 
们 taco 艺 术 农 用户 会 通过 这 个 表单 来 提交 其 美味 的 作品 。 完 整 的 
Thymeleaf 模 板 会 包括 所 有 的 配料 类 型 ， 表 时 如 程序 清 蛙 2.3 所 示 : 


程序 清单 2.3 ”设计 taco 的 完整 页 面 


<1DOCTYPE html> 
<html xmlns="http://www.w3.org/1999/xhtml" 
xmlns:th="http://www.thymeleaf .org > 
<head> 
<title>Taco Cloud</title> 
<link rel="stylesheet" th:href="@{/styles.css}" /> 
</head> 


<body> 
<h1i>Design your tacol</h1> 
<img th:src="Q@{/images/TacoCloud.png}"/> 


<form method="POST" th:object="${design}"> 
<div class="grid"> 
<div class="ingredient-group”" id="wraps"> 
<h3>Designate your wrap:</h3> 
<div th:each="ingredient : ${wrap}"> 
<input name="ingredients" type=" checkbox 


th:value="${ingredient.i 
d}" 
/> 
<Span th:text="${ingredient.name}">INGREDIENT</span><br/> 
</div> 
</div> 


<div class="ingredient-group”" id="proteins"> 
<h3>Pick your protein:</h3> 
<div th:each="ingredient : ${protein}"> 


<input name="ingredients" type="checkbox" th:value="${ingredient.i 


d}" 
/> 
<Span th:text="${ingredient.name}">INGREDIENT</span><br/> 
</div> 
</div> 
<div class="ingredient-group”" id="cheeses'"> 
<h3>Choose your cheese:</h3> 
<div th:each="ingredient : ${cheese}"> 
<input name="ingredients" type="checkbox" th:value="${ingredient.i 
d}" 
/> 
<Span th:text="${ingredient.name}">INGREDIENT</span><br/> 
</div> 
</div> 
<div class="ingredient-group”" id="veggies"> 
<h3>Determine your veggies:</h3> 
<div th:each="ingredient : ${veggies}"> 
<input name="ingredients" type="checkbox”" th:value="${ingredient.i 
d}" 
/> 
<Span th:text="${ingredient.name}">INGREDIENT</span><br/> 
</div> 
</div> 
<div class="ingredient-group”" id="sauces"> 
<h3>Select your sauce:</h3> 
<div th:each="ingredient : $f{sauce}"> 
<input name="ingredients" type="checkbox”" th:value="${ingredient.i 
d}" 
/> 
<Span th:text="${ingredient.name}" >INGREDIENT</span><br/> 
</div> 
</div> 
</div> 
<div> 


<h3>Name your taco creation:</h3> 
<input type="text" th:field="*{name}"/> 
<br/> 


<button>Submit your taco</button> 
</div> 
</form> 


</body> 
</html> 

可 以 看 到 ， 我 们 会 为 各 种 类 型 的 配料 重复 定义 <div> 厂 段 。 男 外 ， 
我 们 还 包含 了 一 个 Submit 投 钮 ， 以 及 用 户 用 来 定义 其 作品 名 称 的 输入 
域 。 


值得 注意 的 是 ， 完 整 的 模板 包含 了 一 个 Taco Cloud 的 logo 图 片 以 及 
对 样式 表 的 <link> 引 用 站 。 在 这 两 个 场景 中 ， 都 使 用 了 Thymeleaf 的 @{} 
操作 符 ， 用 来 生成 一 个 相对 上 下 文 的 路 径 ， 以 便于 引用 我 们 需要 的 襄 态 
制 件 《artifact) 。 正 如 我 们 在 第 1 章 中 所 学 到 的 ， 在 Spring Boot 应 用 中 ， 
前 人 态 内 容 要 帮 到 根 路 径 的 “/static”* 目 录 下 。 


我 们 的 控制 项 和 视图 已 经 完成 了 ， 现 在 我 们 可 以 将 应 用 局 动 起 来 ， 
看 一 下 我 们 的 劳动 成 果 。 运 行 Spring Boot 悄 用 有 很 多 种 方式 。 在 第 1 章 
中 ， 我 为 你 首先 展示 了 如 何 将 应 用 构建 成 一 个 可 执行 的 JAR 文 件 ， 然 后 
通过 java -jar 命 令 来 运行 这 个 JAR。 我 还 展示 了 如 何 直 接 通 过 mvn spring- 
boot:run 构 建 命令 来 运行 应 用 。 

不 官 你 采用 哪 种 方式 来 启动 Taco Cloud 应 用 ， 在 月 动 之 后 都 可 以 通 


过 http://localhost: 8080/design 来 进行 访问 。 你 将 会 看 到 如 图 2.2 所 示 的 一 
个 页 面 O 〇 


SO@@ « 加 localhost 区 A 5 j 男 


Design your taco! 





Designate your wrap: Pick your protein: 
Flour Tortilla Ground Beef 
Corn Tortilla Camitas 
Choose your cheese: Determine your veggies: 
Cheddar Diced Tomatoes 
Monterrey Jack Lettuce 


Select your sauce: 
Salsa 
Sour Cream 
Name your taco creation: 


Submit your taco 


图 2.2” 泻 染 之 后 的 taco 设 计 页 面 


这 看 上 去 非常 不 错 ! 访问 你 站 点 的 taco 艺 术 家 可 以 看 到 一 个 表单 ， 
这 个 表单 中 包含 了 各 种 taco 配 料 ， 他 们 可 以 使 用 这 些 配料 创建 目 己 的 杰 
作 。 但 是 当 他 们 点 击 Submit Your Taco 按 钮 的 时 候 会 发 生 什 么 呢 ? 


我 们 的 DesignTacoController 还 没有 为 接收 创建 taco 的 请 求 做 好 准 
备 。 如 果 提 有 区 设 计 表 单 ， 用 户 束 会 过 到 一 个 错 座 (具体 来 讲 ， 将 会 古 一 
个 HTTP 405 错 误 : Request Method “POST”Not Supported) 。 接 下 来 ， 
我 们 通过 编写 一 些 处 理 表 蛙 提交 的 控制 右 代 人 码 来 修正 这 个 错误 。 


2.2 ”处 理 表 单 提 区 


仔细 看 一 下 视图 中 的 <form> 标 签 ， 你 将 会 发 现 它 的 method 属 性 被 设 
置 成 了 POST。 除 此 之 外 ，<form> 并 没有 声明 action 必 性。 这 意味 着 当 表 
单 提交 的 时 候 ， 浏 览 器 会 收集 表单 中 的 所 有 数据 ， 并 以 HTTP POST 请 求 
的 形式 将 其 发 送 至 服务 器 端 ， 发 送 路 径 与 泻 染 表单 的 GET 请 求 路 径 相 
辣 ， 也 融和 定 “/design”。 


因此 ， 在 该 POST 请 求 的 接收 端 ， 我 们 需要 有 一 个 控制 器 处 理 方 
法 。 在 DesignTacoController 中 ， 我 们 会 编写 一 个 新 的 处 理 器 方法 来 处 理 
针对 “/design” 失 POST 请 求 。 


在 程序 清单 2.2 中 ， 我 们 曾经 使 用 @GetMapping 注 解 声 明 
showDesignFormO 方 法 要 处 理 针 对 “design” 的 HITP GET 请 求 。 与 
@GetMapping 处 理 GET 请 求 关 似 ， 我 们 可 以 使 用 @PostMapping 来 处 理 
POST 请 求 。 为 了 处 理 taco 设 计 的 表单 提交 ， 在 DesignTacoController 中 添 
加 程序 清单 2.4 所 述 的 processDesign(0) 方 法 。 


程序 清单 2.4， 使 用 @PostMapping 来 处 理 POST 请 求 


QPostMapping 

public String processDesign(Taco design) { 
// Save the taco design... 
// We'll do this in chapter 3 


log.info("Processing design: ”+ design); 


return “redirect:/orders/current"; 





如 processDesign() 方 法 所 示 ，@PostMapping 与 类 级 别 的 
(@@RequestMapping 协 作 ， 指 定 processDesign() 方 法 要 处 理 针 对 “/design” 的 
POST 请 求 。 我 们 所 需要 的 正 是 以 这 种 方式 处 理 taco 艺 术 家 的 表单 提交 。 


当 表 单 提 交 的 时 候 ， 表 单 中 的 输入 域 会 绑 定 到 Taco 对 象 〈 这 个 交会 
在 下 面 的 程序 清单 中 进行 介绍 ) 的 属性 中 ， 访 对 象 会 以 参数 的 形式 传递 
给 processDesign()。 从 这 里 开始 ，processDesign() 束 可 以 针对 Taco 对 象 采 
取 任 意 操 作 了 了 。 


程序 清单 2.5 定义 taco 设 计 的 领域 对 象 


package tacos; 

import JjJava.util.List,; 
import lombok.Data; 
@Data 

public class Taco 1{ 


private String name; 
private List<String> Ingredients ; 





我 们 可 以 看 到 ，Taco 是 一 个 非常 简单 的 Java 领 域 对 象 ， 其 中 包含 了 
几 项 属性 。 与 jngredient 类 似 ，Taco 类 也 琴 加 了 @Data 注 和 解 ， 会 在 编译 期 
目 动 生成 必要 的 JavaBean 方 法 ， 所 以 这 些 方法 在 运行 期 是 可 用 的 。 


回 过 头 来 再 看 一 下 程序 清单 2.3 中 的 表单 ， 你 会 及 现 其 中 包含 多 个 
checkbox 元 素 ， 它 们 的 名 字 都 是 ingredients， 另 外 还 有 一 个 名 为 name 的 
文本 输入 元 系 。 表 单 中 的 这 些 输入 域 直 接 对 应 Taco 类 的 ingredients 和 和 
name 属 性 。 


表单 中 的 name 输 入 域 只 需要 捕获 一 个 向 单 的 文本 什 。 因 此 ，Taco 的 
name 属 性 是 String 类 型 的 。 配 料 的 复 选 框 也 有 文本 值 ， 但 是 用 户 可 能 会 
选择 一 个 或 多 个 ， 所 以 它们 所 绑 定 的 ingredients 属 性 是 一 个 
List<String>， 能 够 捕获 选中 的 每 种 配料 。 


processDesign() 方 法 对 Taco 对 象 没 有 执行 任何 操作 。 实 际 上 ， 这 个 
方法 什么 都 役 做 。 现 在 ， 这 样 是 可 以 的 。 到 第 3 章 ， 我 们 将 会 添加 一 些 
持久 化 的 逻辑 ， 将 提交 的 Taco 保 存 到 一 个 数据 库 中 。 


与 showDesignForm() 方 法 类 似 ，processDesign0) 最 后 也 人 返回 了 一 个 
String 类 型 的 值 。 同 样 与 showDesignForm() 相 似 ， 返 回 的 这 个 值 代表 了 
一 个 要 展现 给 用 户 的 视图 。 但 是 ， 区 别 在 于 processDesign() 人 返回 的 值 币 
有 “redirect:” 前 级 ， 表 明 这 是 一 个 午 定 同 视 图 。 更 其 体 地 讲 ， 它 表明 在 
processDesign() 完 成 之 后 ， 用 户 的 浏览 器 将 会 午 定 同 到 相对 路 


径 “/order/current”。 
这 里 的 想法 是 在 创建 完 taco 后 ， 用 户 将 会 被 重 定 回 到 一 个 订单 表单 
页 面 ， 在 这 里 用 户 可 以 创建 一 个 订单 ， 将 他 们 所 创建 的 taco 快 递 过 去 。 


但 是 ， 我 们 现在 还 没有 人 处理“/orders/current” 请 求 的 控制 器 。 


根据 已 经 学 到 的 关于 @Controller、@RequestMapping 和 
@GetMapping 的 知识 ， 我 们 可 以 很 容易 地 创建 这 样 的 控制 磊 。 它 应 该 如 
程序 清单 2.6 所 示 。 


程序 清单 2.6 ”展现 taco 订 单 表 单 的 控制 器 





package tacos .Web ; 

import Javax.validation.Valid; 

Import org.springframework.stereotype.Controller.:; 

import org.springframework.ui.Model; 

import org.springframework.validation.Errors; 

Import org.springframework.web.bind.annotation.GetMapping; 
import org.springframework.web.bind.annotation.RequestMapping; 
Import lombok.extern.slf4].S1f4]; 

Import tacos.Order; 


QControllenr 
@QRequestMapping("/orders") 
public class OrderController { 


@QGetMapping("/current") 

public String orderForm(Model] model) { 
model.addAttribute("order", new Order()); 
return "orderForm"; 


} 





在 这 里 ， 我 们 再 次 使 用 Lombok @SIlf4j 注 解 在 运行 期 创建 一 个 SLF4J 
Logger 对 象 。 稍 后 ， 我 们 将 会 使 用 这 个 Logger 记 录 所 提交 订单 的 详细 信 


自 


J 已 vo 


类 级 别 的 @RequestMapping 指 明 这 个 控制 器 的 请 求 处 理 方法 都 会 处 
理 跤 径 以 “/orders” 开 头 的 请 求 。 当 与 方法 级 别 的 @GetMapping 注 解 结合 
之 后 ， 它 束 能 够 指定 orderForm() 方 法 ， 会 处 理 针 对 “/orders/current” 的 
HTTP GET 请 求 。 


orderForm() 方 法 本 里 非常 简单 ， 只 是 返回 了 一 个 名 为 orderForm 的 
逻辑 视图 名 。 在 第 3 章 学 习 完 如 何 将 所 创建 的 taco 保 存 到 数据 库 之 后 ， 我 
们 将 会 重新 回 到 这 个 方法 并 对 其 进行 修改 ， 用 一 个 Taco 对 象 的 列表 来 填 
元 模型 并 将 其 放 到 订单 中 。 


orderForm 视 图 是 由 名 为 orderForm.html 的 Thymeleaf 模 板 来 提供 的 ， 
如 程序 清单 2.7 所 示 。 


程序 清单 2.7 ”一 个 taco 订 单 表单 视 网 


<LIDOCTYPE html> 
<html xmlns="http://www.w3.org/1999/xhtml" 


xmlns:th="http://www.thymeleaf.org"> 
<head> 
<title>Taco Cloud</title> 
<link rel="stylesheet" th:href="@{/styles.css}" /> 
</head> 


<body> 


<form method="POST" th:action="@{/orders}" th:object="${order}"> 
<h1i>Order your taco creations!</h1i> 


<img th:src="@{/images/TacoCloud.png}"/> 
<a th:href="@{/design}" id="another">Design another taco</a><br/> 


<div th:if="${#fields.hasErrors()}"> 
<span class="validationError"> 
Please correct the problems below and resubmit. 
</span> 
</div> 
<h3>Deliver my taco masterpieces to...</h3> 
<label for= name >Name: </label> 
<input type="text" th:field="*{name}"/> 
<br/> 


<l]abel for="street">Street address: </label> 
<input type="text" th:field="*{street}"/> 
<br/> 


<label for="city">City: </label> 
<input type="text" th:field="*{city}"/> 
<br/> 


<l]abel for="state">State: </label> 
<input type="text" th:field="*{state}"/> 
<br/> 


<label for="zip">Zip code: </label> 
<input type="text" th:field="*{zip}"/> 
<br/> 


<h3>Here's how I'l1l1 pay...</h3> 

<label for="ccNumber">Credit Card #: </label> 
<input type="text" th:field="*{ccNumber}"/> 
<br/> 


<label for="ccExpiration">Expiration: </label> 
<input type="text" th:field="*{ccExpiration}"/> 
<br/> 


<label for= ccCcCVV >CVV: </label> 
<input type="text" th:field="*{ccCVW}"/> 
<br/> 


<input type="submit" value="Submit order /> 
</form> 


</body> 
</html> 





从 很 大 程度 上 来 讲 ，orderForm.html 就 是 典型 的 HTML/Thymeleaf 内 
容 ， 不 需要 过 多 关注。 但 是 ， 需 要 注意 一 点 ， 这 里 的 <form> 标 位 和 程序 
清单 2.3 中 的 <form> 标 签 有 所 不 同 ， 它 指定 了 一 个 表单 的 action。 如 果 不 
指定 action， 那 么 表单 将 会 以 HTTP POST 的 形式 提交 到 与 展现 该 表单 相 
癌 的 URL 上 。 在 这 里 ， 我 们 明确 指明 表单 要 POST 所 区 到 ”orders” 上 《使 
用 Thymeleaf 的 @{...} 操 作 符 指定 相对 上 下 文 的 路 任 〉。 


因此 ， 我 们 需要 在 OrderController 中 添加 另外 一 个 方法 ， 以 便于 处 
理 针 对 “orders” 的 POST 请 求 。 我 们 在 第 3 章 才 会 对 订单 进行 持久 化 ， 在 
此 之 前， 我 们 让 它 尽 可 能 人 简单， 如 程序 清单 2.8 所 示 。 





程序 清单 2.8 处理 taco 订 单 的 提交 


QPostMapping 
public String processOrder(Order order) { 


log.info("Order submitted: ”+ order); 
return "redirect:/"; 


} 





当 调 用 processOrder0 方 法 处 理 所 提 交 的 订单 时 ， 我 们 会 得 到 一 个 
Order 对 象 ， 它 的 属性 绑 定 了 所 提交 的 表 蛙 域 。Order 与 Taco 非 党 相似 ， 
是 一 个 非常 简单 的 类 ， 其 中 包含 了 订 早 的 信息 ， 如 程序 清单 2.9 所 示 。 


package tacos; 


程序 清单 2.9 taco 订 单 的 领域 对 象 


import Javax.validation.constraints.Digits; 

Import javax.validation.constraints.Pattern,; 

Import org.hibernate.validator.constraints.CreditCardNumber; 
Import org.hibernate.validator.constraints.NotBlank; 

import lombok.Data; 


@Data 


public class Order { 


private String 
private String 
private String 
private String 
private String 
private String 
private String 
private String 


name ; 
street, 

city; 

State ; 

zip; 
CCNumber ; 
ccExpiration; 
CCCVV ; 





现在 ， 我 们 已 经 开发 了 OrderController 和 订单 表单 的 视图 ， 接 下 来 
我 们 可 以 竹 试 运行 一 下 。 打 开 浏 顷 并 访问 http://localhost:8080/design， 
为 taco 选 择 一 些 配料 ， 并 点 击 “Submit Your Taco” 按 钮 ， 将 会 看 到 如 图 
2 HR 


和 国力 《 外] localhost 


Order your taco creations! 






下 


Design another taco 
Deliver my taco masterpieces to... 


Name: 

Street address: 
City: 

State: 

Zip code: 


Here's how I'll pay... 


Credit Card #: 
Expiration: 
CVV: 


Submit order 


图 2.3 ”taco 订单 表单 


填充 表单 的 一 些 输 入 域 并 点 击 “Submit order” 按 钮 。 请 关注 应 用 的 日 
蕊 来 但 看 你 的 订单 信息。 在 我 尝试 运行 的 时 候 ， 日 志 条 目 如 下 所 示 (为 
了 适应 页 面 的 宽度 ， 重 新 进行 了 格式 化 ) : 


Order submitted: Order(name=Craig Walls,street1=1234 7th Street, 
city=Somewhere, state=Who knows?, zip=zipzap, ccNumber=Who can guess? 





2 
ccExpiration=Some day, ccCVV=See-vee-vee) 


如 采 仔 细 奏 看 上 述 测试 订单 的 日 志 ， 吏 会 及 现 义 管 processOrder() 方 
法 完成 了 它 的 工作 并 处 理 了 表单 提交 ， 但 是 它 让 一 些 错误 的 信息 混入 了 
进来 。 表 单 中 的 大 多 数 输 入 域 包含 的 可 能 部 是 不 正确 的 信息 。 我 们 接 下 
来 添加 一 些 校 验 ， 确 你 所 提交 的 数据 至 少 与 所 需 的 信息 比较 接近 。 


2.3” 校 验 表 单 输入 


在 设计 靳 的 taco 作 品 的 时 候 ， 如 朱 用 户 没 有 选择 配料 或 者 没有 为 他 
们 的 作品 指定 名 称 ， 那 么 将 会 怎样 呢 ? 妆 提交 表单 的 时 候 ， 没 有 填写 所 
条 的 地 址 输入 域 义 将 友 生 什么 呢 ? 或 者 ， 在 信用 卡 域 中 输入 了 一 个 根本 
不 合法 的 数 子 ， 义 该 怎么 办 呢 ? 


束 目 前 的 情况 来 看 ， 没 有 什么 能 够 阻止 用 户 在 创建 taco 有 的 时 候 不 选 
择 任何 配料 ， 或 者 输入 空 的 快递 地 址 ， 甚 至 将 他 们 喜欢 的 歌词 作为 信用 
卡 写 进行 提交 。 这 是 因为 我 们 还 没有 指明 这 些 输入 域 访 如 何 进 行 校 验 。 


有 种 校 验 方法 束 是 在 processDesign() 和 processOrder() 方 法 中 添加 大 
量 乱 七 八 糟 的 if/then 代 码 块 ， 逐 个 检查 ， 确 你 每 个 输入 域 都 满足 对 应 的 
校 验 规 则 。 但 是 ， 这 样 会 非 名 烦琐， 并 且 难 以 阅读 和 调试 。 


比较 壮 运 的 是 ，Spring 文 持 Java 的 Bean 校 验 API (Bean Validation 
API， 也 被 称 为 JSR-303) 。 这 样 的 话 ， 我 们 能 够 更 容易 地 声明 检验 规 
则 ， 而 不 必 在 应 用 程序 代码 中 显 式 编写 声明 过 辑 。 价 助 Spring Boot， 要 
在 项 目 中 湛 加 校 验 库 ， 我 们 甚至 不 需要 做 任何 特殊 的 操作 ， 这 是 因为 
Validation API 以 及 Validation API 的 Hibernate 实 现 将 会 作为 Spring Boot 


web starter 的 传递 性 依赖 目 动 添加 到 项 目 中 。 
要 在 Spring MVC 中 应 用 校 验 ， 我 们 需要 。 


。 在 要 被 校 验 的 关上 声明 校 验 规则 : 其 体 到 我 们 的 场景 中 ， 也 吏 是 
Taco 关 。 

。 在 控制 硕 方 法 中 声明 要 进行 校 验 : 其 体 来 讲 ， 也 了 吏 是 
DesignTacoController 的 processDesign0 方 法 和 OrderController 的 
processOrder() 方 法 。 

。 修改 表单 视图 以 展现 校 验 错 诺 。 

Validation API 提 供 了 一 些 可 以 汐 加 到 领域 对 象 上 的 注解 ， 以 便于 声 
明 校 验 规 则 。Hibernate 的 Validation AP 实现 又 添加 了 一 些 校 验 注 解 。 接 
下 来 ， 我 们 看 一 下 如 何 使 用 其 中 的 一 些 注 解 来 校 验 用 户 提交 的 Taco 和 
Order。 


2.3.1 声明 校 验 规 则 


对 于 Taco 类 来 说 ， 我 们 想 要 确保 name 属 性 不 能 为 空 或 null， 同 时 希 
望 选中 的 配料 至 少 要 包 侣 一 项 。 程 序 清 单 2.10 将 展示 更 新 后 的 Taco 关 ， 
它 使 用 @NotNull 和 @Size 注 解 来 声明 这 些 校 验 规则 。 


程序 清单 2.10 ”为 Taco 领 域 类 添加 校 验 





package tacos; 

Import java.util.List; 

import Javax.validation.constraints.NotNull,; 
import Javax.validation.constraints.Size; 
import lombok.Data; 


@Data 
public class Taco 1{ 


@QNotNull 

@Size(min=5, message="Name must be at least 5 characters long") 
private String name; 

@Size(min=1, message="You must choose at least 1 ingredient") 
private List<String> Ingredients ; 





我 们 可 以 友 现 ， 除 了 要 求 name 属 性 个 为 null 之 外 ， 我 们 还 声明 了 它 
的 值 在 长 度 上 至 少 要 有 5 个 字符 。 


在 对 提交 的 taco 订 单 进行 校 验 时 ， 我 们 必须 要 给 Order 类 添加 注解 。 
对 于 地 址 相关 的 属性 ， 我 们 只 想 确 保 用 户 没 有 提交 空 日 字段 。 为 此 ， 我 
们 可 以 使 用 Hibernate Validator 的 @NotBlank 注 解 。 


但 是 ， 文 付 相 关 的 字段 束 比 较 复 洒 了 。 我 们 不 仅 要 确保 ccNumber 属 
性 不 为 室 ， 还 要 你 证 它 所 包含 的 值 是 一 个 合法 的 信用 卡 写 人 码 。 
CCExpiration 属 性 必须 符合 MM/YY 格 式 《〈 两 位 的 月 份 和 年 份 ) 。ccCVV 
属性 需要 是 一 个 3 位 的 数字 。 为 了 实现 这 种 校 验 ， 我 们 需要 其 他 的 一 些 
Java Bean Validation API 注 解 ， 并 结合 来 日 Hibernate Validator 的 注解 。 
程序 清单 2.11 展 现 了 校 验 Order 类 所 需 的 变更 。 


程序 清单 2.11 校 验 订单 的 字段 





package tacos; 

import Javax.validation.constraints.Digits; 

Import javax.validation.constraints.Pattern,; 

Import org.hibernate.validator.constraints.CreditCardNumber; 
import javax.validation.constraints.NotBlank; 

import lombok.Data; 


@Data 


public class Order { 


QNotBlank(message="Name is required") 
private String name ; 


@QNotBlank(message="Street is required") 
private String street; 


@NotBlank(message="City is required") 
private String city; 


@QNotBlank(message="State is required") 
private String state; 


@QNotBlank(message="Zip code is required") 
private String zip; 


@CreditCardNumber (message="Not a valid credit card number") 
private String ccNumber; 


@Pattern(regexp="^(e[1-9] |1[8-2])([\\/1)([1-9][e6-9])$", 
message="Must be formatted MM/YY") 


private String ccExpiration; 


QDigits(integer=3, fraction=6@, message="Invalid CVV") 
private String CCCVV 


我 们 可 以 看 到 ，ccNumber 属 性 添加 了 @CreditCardNumber 注 解 。 这 
个 注解 声明 该 属性 的 全 必须 是 合法 的 信用 卡号 ， 它 要 能 通过 Luhn 算 法 的 
检查 。 这 能 防止 用 尸 有 童 或 无 音 地 输入 错误 的 数据 ， 但 是 该 检查 并 不 能 
确 人 这 个 信用 卡号 真有 的 分 配给 了 了 菏 个 账 尸 ， 也 不 能 你 证 这 个 账号 能 够 用 
来 进行 文 付 。 


令 人 进 憾 的 是 ， 目 前 还 没有 现成 的 注解 来 校 验 ccExpiration 属性 的 
MM/YY 格 式 。 在 这 里 ， 我 使 用 了 @pPattern 注 解 并 为 其 提供 了 一 个 正则 
表达 式 ， 人 确保 属性 值 符合 预期 的 格式 。 如 果 你 想 知 道 如 何 解 释 这 个 正则 


表达 却 ， 那 么 我 建议 你 参考 一 些 在 线 的 正则 表达 却 指 两 。 正 则 表达 陈 是 
一 种 魔法 ， 已 经 超出 了 本 书 的 范围 。 


最 后 ， 在 ccCVV 属 性 上 添加 了 Q@Digits 注 解 ， 能 够 确保 它 的 值 包含 3 
位 数字 。 


所 有 的 校 验 注 解 都 包含 了 一 个 message 属 性 ， 该 属性 定义 了 当 输 入 
的 信息 不 满足 声明 的 校 验 规则 时 要 给 用 户 展 现 的 消 妃 。 


2.3.2 ”在 表单 绑 定 的 时 候 执 行 校 验 


现在 ， 我 们 已 经 声明 了 如 何 校 验 Taco 和 Order， 接 下 来 我 们 要 重新 
修改 每 个 控制 右 ， 让 表单 在 POST 提交 至 对 应 的 控制 需 方 法 时 执行 对 应 
的 校 验 。 


要 校 验 提交 的 Taco， 我 们 需要 为 DesignTacoController 中 
processDesign(O) 方 法 的 Taco 参 数 添 加 一 个 Java Bean Validation API 的 
@Valid 注 解 ， 如 程序 清单 2.12 所 示 。 


程序 清单 2.12 ” 校 验 POST 提 交 的 Taco 





QPostMapping 
public String processDesign(@Valid Taco design, Errors errors) { 
if (errors.hasErrors()) { 
return "design"; 


} 


// Save the taco design... 

// We'll do this in chapter 3 
log.info("Processing design: ”+ design); 
return “redirect:/orders/current"; 


DJ 


@Valid 注 解 会 告诉 Spring MVC 要 对 提交 的 Taco 对 象 进行 校 验 ， 而 
校 验 时 机 是 在 它 绑 定 完 表单 数据 之 后 、 调 用 processDesign(O 之 前 。 如 采 
存在 校 验 错误 ， 那 么 这 些 错误 的 细 贡 将 会 捕获 到 一 个 Errors 对 象 中 并 传 
圳 给 processDesign()。processDesign() 方 法 的 前 儿 行 会 查阅 Errors 对 象 ， 
调用 其 hasErrors0) 方 法 判断 是 否 有 校 验 销 误 。 如 果 存 在 校 验 错误 ， 那 么 
这 个 方法 将 不 会 处 理 Taco 对 象 并 返回 “design” 视 儿 名 ， 表 单 会 重新 展 
现 。 


为 了 对 提交 的 Order 对 象 进 行 校 验 ，OrderController 的 processOrder() 
方法 也 需要 进行 基 似 的 变更 ， 如 程序 清单 2.13 所 示 。 


程序 清单 2.13 ” 校 验 POST 提 交 的 Order 


QPostMapping 
public String processOrder(@Valid Order order, Errors errors) { 
if (errors.hasErrors()) { 
return "orderForm"; 


} 


log.info("Order submitted: " + order); 
return "redirect:/"; 





在 这 两 个 场景 中 ， 如 果 没 有 校 验 错误 ， 那 么 方法 都 会 允许 处 理 提交 
的 数据 。 如 果 存在 校 验 错误 ， 那 么 请 求 将 会 被 转发 至 表单 视图 上 ， 以 便 
让 用 户 有 机 会 纠正 他 们 的 错误 。 


但 是 ， 用 户 该 如 何 知 道 有 哪些 要 纠正 的 错误 呢 ? 如 采 我 们 无 法 指出 
表单 上 的 铺 误 ， 那 么 用 户 只 能 不 断 狂 汕 如 何 才 能 成 功 提 交 表 单 。 


2.3.3 ”展现 校 验 蚀 谍 


Thymeleaf 提 供 了 便捷 访问 Errors 对 和 象 的 方法 ， 这 就 是 借助 fields 及 其 
th:errors 属 性 。 举 例 来 说 ， 为 了 展现 信用 卡 字 段 的 校 验 错 误 ， 我 们 可 以 
还 加 一 个 <span> 元 素 ， 访 元 素 会 将 对 错误 的 引用 用 到 订单 的 表单 模板 
上 ， 如 程序 清单 2.14 所 示 。 


程序 清单 2.14 ”展现 校 验 错误 


<label for="ccNumber">Credit Card #: </label> 
<input type="text" th:field="*{ccNumber}"/> 


<span class="validationError" 
th:if="${#fields.hasErrors('ccNumber' )}" 
th:errors="*{ccNumber}">CC Num Error</span> 





在 这 里 ，<span> 元 素 使 用 class 属 性 来 为 错误 添加 样式 ， 以 引起 用 户 
的 注意 。 际 此 之 外 ， 它 还 使 用 th:if 属 性 来 决定 是 人 否 要 显示 该 元 厅 。fields 
属性 的 hasErrors() 方 法 会 检查 ccNumber 域 是 否 存 在 错误 ， 如 果 存 在 ， 就 


将 会 泻 染 <span>。 


th:errors 属 性 引用 了 ccNumber 输 入 域 ， 如 果 访 输入 域 存 在 错误 ， 那 
么 它 会 将 <span> 元 素 的 占 位 符 内 容 蔡 换 为 校 验 信息 。 


在 为 订单 表单 的 其 他 和 输入 域 都 添加 类 似 的 <span> 标 釜 之 后 ， 如 琳 扒 
交错 误 信 息 ， 那 么 表单 将 会 如 图 2.4 所 示 。 错 误 信 息 提 示 姓 名 、 城 市 和 
邮政 编码 字段 为 室 ， 而 且 所 有 文 付 相 关 的 输入 域 均 未 满足 校 验 条 件 。 


OO@ 《 四] localhost © 由 口 


Order your taco creations! 






二 


Design another taco 
Please correct the problems below and resubmit. 
Deliver my taco masterpieces to... 
Name: Name is required 
Street address: 1234 7th Street 
City: City is required 
State: VT 
Zip code: Zip code is required 
Here's how 1'll pay... 
Credit Card #: Who can guess? Not a valid credit card number 
Expiration: Some day Must be formatted MM/Y Y 
CVV: See-vee-vee Invalid CVV 


Submit order 


图 2.4 在 订单 表单 上 展现 校 验 错误 


现在 ， 我 们 的 Taco Cloud 控 制 硕 不 仅 能 够 展现 和 捕获 输入 ， 还 能 校 
验 用 户 提 交 的 信息 是 否 满足 一 定 的 基本 验证 规则 。 接 下 来 ， 我 们 后 退 一 
步 ， 重 新 考虑 一 下 第 1 章 中 的 HomeController， 人 介绍 一 种 符 代 实现 方案 。 


2.4 使 用 从 图 控制 疮 


到 目前 为 止 ， 我 们 已 经 为 Taco Cloud 应 用 编写 了 3 个 控制 器 。 尽 管 这 


3 个 控制 桌 服 务 于 应 用 程序 的 人 不同 功能 ， 但 古 它 们 基本 上 痢 订 人 循 相同 的 
编程 模型 : 


。 它们 都 使 用 了 @Controller 注 解 ， 表 明 它 们 是 控制 痴 类， 并 且 应 该 被 
Spring 的 组 件 扫 摘 功能 目 动 发 现 并 初始 化 为 Spring 心 用 上 下 文中 的 
bean:; 

。 除了 HomeController 之 外 ， 其 他 的 控制 大 都 在 美 级 别 使 用 了 
@RequestMapping 注 解 ， 据 此 定义 该 控制 问 所 处 理 的 基本 请 求 模 
F 

。 它们 都 有 一 个 或 多 个 市 @GetMapping 或 @PostMapping 注 解 的 方 
法 ， 指 明了 访 由 哪个 方法 来 处 理 荣 种 类 型 的 请 求 。 


我 们 所 编写 的 大 部 分 控制 器 都 将 这 循 这 个 模式 。 人 但是， 如果 一 个 控 
制 改 非常 和 测 单 ， 不 需要 项 元 模型 或 处 理 输入 《在 我 们 的 场景 中 ， 也 驳 是 
HomeController) ， 那 么 还 有 一 种 方式 可 以 定义 控制 天 。 请 参考 下 面 的 
程序 清单 2.15 来 学 习 如 何 声明 视 网 控 制 闫 : 也 束 是 只 将 请 求 转发 到 视图 
而 不 做 其 他 事情 的 控制 医 。 


程序 清单 2.15 ”声明 视图 控制 硕 





package tacos .Web ; 


Import org.springframework.context.annotation.Configuration; 
import 
org.springframework.web.servlet.config.annotation.ViewControllerRegis 
try 
) 
Import org.springframework.web.servlet.config.annotation.WebMvcConfigurer:; 


@Configuration 
public class WebConfig implements WebMvcConfigurer { 


QOverride 
public void addViewControllers(ViewControllerRegistry registry) { 


registry.addViewController("/").setViewName("home"); 


} 





关于 WebConfig， 最 需要 注意 的 事情 束 是 它 实 现 了 
WebMvcConfigurer 接 口 。WebMvcConfigurer 定 义 了 多 个 方法 来 配置 
Spring MVC。 尽 管 只 是 一 个 接口 ， 但 是 它 担 供 了 所 有 方法 的 默认 实现 ， 
只 需要 履 闸 所 需 的 方法 即 可 。 在 本 例 中 ， 我 们 复 瘟 了 addViewControllers 
为 


addViewControllers(0) 方 法 会 接收 一 个 ViewControllerRegistry 对 象 ， 
我 们 可 以 使 用 它 注册 一 个 或 多 个 视图 控制 句 。 在 这 里 ， 我 们 调用 registry 
的 addViewController(0) 方 法 ， 将 “/ 传 递 了 进去 ， 视 图 控制 右 将 会 针对 议 
路 径 执行 GET 请 求 。 这 个 方法 会 返回 ViewControllerRegistration 对 象 ， 我 
们 马上 基于 该 对 象 调 用 了 setViewName(0) 方 法 ， 用 它 指 明 当 请 求 “/ 的 时 
候 要 转发 到 “home” 视 图 上 。 


如 前 文 所 示 ， 我 们 用 配置 类 中 的 几 行 代 但 束 奉 换 了 HomeController 
类 。 现 在 ， 我 们 可 以 删除 HomeController 了 ， 应 用 的 功能 应 该 和 之 前 完 
全 一 样 。 唯 一 需要 注意 的 是 ， 我 们 要 重新 找到 第 1 和 章 中 的 
HomeControllerTest 类 ， 从 @WebMvcTest 注 解 中 移 除 对 HomeController 的 
引用 ， 这 样 测 试 类 的 编译 才 不 会 报错 。 


在 这 里 ， 我 们 创建 了 一 个 新 的 WebConfig 配 置 类 来 存放 视图 控制 器 
的 声明 。 但 是， 所 有 的 配置 类 都 可 以 实现 WebMvcConfigurer 接 口 并 禾 声 
addViewController 方 法 。 举 例 来 说 ， 我 们 可 以 将 相同 的 视图 控制 右 声 明 


洪 加 到 TacoCloudApplication 引 导 类 中 ， 如 下 所 示 : 


@SpringBootApplication 
public class TacoCloudApplication implements WebMvcConfigurer { 


public static void main(String[] args) { 
SpringApplication.run(TacoCloudApplication.class, args); 


QOverride 
public void addViewControllers(ViewControllerRegistry registry) { 
registry.addViewController("/").setViewName("home"); 





采用 扩展 已 有 配置 类 的 方式 能 够 避免 创建 新 的 配置 类 ， 从 而 减少 项 
上 中 制 件 的 数量 。 但 是 ， 我 倾 回 于 为 每 种 配 疼 Web、 数据 、 安 全 等 ) 
创建 新 的 配置 类 ， 这 样 能 够 你 持 应 用 的 引导 配置 类 尺 可 能 地 整洁 和 人 简 
Hs 


在 视图 控制 套 方 面 ， 或 者 更 通俗 地 来 讲 ， 在 控制 硕 将 请 求 所 转 友 到 
的 视图 方面 ， 到 目前 为 止 ， 我 们 都 是 使 用 Thymeleaf 来 实现 所 有 视图 
的 。 我 很 喜欢 Thymeleaf， 但 是 你 可 能 想 要 为 你 的 应 用 选择 不 同 的 模板 
模型 ， 下 面 让 我 们 来 看 一 下 Spring 所 能 文 持 的 众多 视图 方案 。 


2.5 ”选择 视图 模板 库 
在 大 多 数 情况 下 ， 视 图 模板 库 的 选择 完全 取决 于 个 人 喜好 。Spring 


非 名 灵活， 能 够 文 持 很 多 种 见 的 借 板 方案 。 除 了 个 别 情况 之 外 ， 你 所 选 
择 的 模板 库 本 号 甚 至 不 知道 它 在 与 Spring 协作 。 


表 2.2 列 出 Spring Boot 目 动 配置 功能 所 文 持 的 模板 方案 。 


表 2.2 文 持 的 模板 方案 


模板 Spring Boot starter 依 颊 
Groovy Templates spring-boot-starter-groovy-templates 


Java Server Pages (JSP) 无 (由 Tomcat 或 Jetty 提 供 ) 
Thymeleaf spring-boot-starter-thymeleaf 





通常 来 讲 ， 你 只 需要 选择 想 要 的 视图 模板 库 ， 将 其 作为 依赖 项 添加 
到 构建 文件 中 ， 然 后 就 可 以 在 “/templates” 目 录 下 (在 基于 Maven 或 
Gradle 构 建 的 项 目 中 ， 它 会 在 “src/main/resources” 日 录 下 ) 编写 模板 了 。 
Spring Boot 会 探测 到 你 所 选择 的 模板 库 ， 并 目 动 配 置 为 Spring MVC 控 制 
复生 成 视图 所 再 的 各 种 组 件 。 


在 Taco Cloud 应 用 中 ， 我 们 已 经 按照 这 种 方式 使 用 了 Thymeleaf 模 板 
库 。 在 第 1 草 中 ， 在 初始 化 项 目的 时 候 ， 我 们 选择 了 Thymeleaf 复 选 框 。 
这 样 会 目 动 将 Spring Boot 的 Thymeleaf starter 依 赖 添 加 到 pom.xml 文 件 


中 。 当 应 用 局 动 的 时 候 ，Spring Boot 的 目 动 配置 功能 会 探测 到 存在 
Thymeleaf 并 上 自动 为 我 们 配置 Thymeleaf bean。 我 们 所 需要 做 的 区 是 
在 “/templates” 中 开始 编写 模板 。 


如 果 你 想 要 使 用 不 同 的 柑 板 亩 ， 只 需要 在 项 目 和 初始 化 的 时 候选 择 它 
或 者 编 和 辑 已 有 的 项 目 构 建文 件 ， 将 新 选择 的 模板 库 洪 加 进来 即 可 。 


例如 ， 我 们 想 要 使 用 Mustache 来 蔡 换 Thymeleaf， 没 有 问题 ! 只 需 
要 找到 pom.xml 文 件 ， 并 将 如 下 的 代 但 


<dependency> 
<groupId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-thymeleaf</artifactId> 
</dependency> 





普 换 为 : 


<dependencyy> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-mustache</artifactId> 
</dependency> 





当然 ， 我 们 还 需要 确保 按照 Mustache 语 法 来 编写 模板 ， 而 不 是 再 使 
用 Thymeleaf 标 答 。Mustache 的 特定 用 法 《以 及 其 他 备 选 模板 语言 ) 超 
出 了 本 书 的 范围 ， 但 是 我 在 这 里 给 你 一 个 直观 的 ey 让 你 明日 大 致 会 
是 什么 样子 。 如 下 代码 是 Mustache 模 板 的 一 个 厂 段 ， 它 能 够 痊 梁 taco 设 
计 表 单 中 的 某 个 配料 组 : 





<h3>Designate your wrap:</h3> 
{{#wrap}} 
<div> 
<input name="ingredients" type="checkbox”" value="{{id}}" /> 


<span>{{name}}</span><br/> 
</div> 


{{/wrap}} 


这 是 2.1.3 小 市 中 Thymeleaf 代 人 码 片 段 的 Mustache 等 价 实现 。 
{{#wrap}} 代 人 码 块 (结尾 对 应 使 用 {{/wrap}}) 会 表 历 请 求 中 key 为 wrap 的 
属性 并 为 每 个 条 目 泻 染 租 入 式 HTML。{{id}} 和 {{name}} 标 签 分 别 会 引 
用 每 个 条 目 “〈 应 该 是 一 个 mgredient) 的 id 和 name 属 性 。 


你 可 能 已 经 注意 到 了 ， 在 表 2.2 中 ，JSP 并 不 需要 在 构建 文件 中 添加 
任何 特殊 的 依赖 。 这 是 因为 Servlet 容 需 本 喘 《〈 默 认 是 Tomcat) 会 实现 
JSP， 因 此 不 需要 额外 的 依 顿 。 但 是 ， 如 采 你 选择 使 用 JSP， 会 有 另外 一 
个 问题 。 事 实 上 ，Java Servlet 容 需 包 括 般 入 式 的 Tomcat 和 Jetty 容 髓 ， 通 
常会 在 “WEB-INF” 目 录 下 寻找 JSP。 如 果 我 们 将 应 用 构建 成 一 个 可 执行 
的 JAR 文 件 ， 就 无 法 满足 这 种 需求 了 。 因 此 ， 只 有 在 将 应 用 构建 为 WAR 
文件 并 部 萌 a 到 传统 的 Servlet 容 疾 中 时 ， 才 能 选择 JSP 方 宁 。 如 果 你 想 要 
构建 可 执行 的 JAR 文 件 ， 那 么 必须 选择 Thymeleaf、FreeMarker 或 表 2.2 中 
的 其 他 方案 。 


绥 存 模板 


堆 认 情况 下 ， 模 板 只 有 在 第 一 次 使 用 的 时 候 解析 一 次 ， 解 析 的 结 末 
会 被 后 续 的 请 求 所 使 用 。 对 于 生产 环境 来 六 ， 这 是 一 个 很 棒 的 特性 ， 写 
能 防止 每 次 请 求 时 多 余 的 模板 解析 过 程 ， 因 此 有 助 于 提升 性 能 。 


但 是 ， 在 开 友 期 ， 这 个 特性 就 不 太 友 好 了 。 假 设 我 们 局 动 完 应 用 之 


后 访问 taco 的 设计 页 面 ， 然 后 决定 对 和 它 做 一 些 修 改 ， 但 是 当 我 们 刷新 
Web 浏 师 右 的 时 候 显 示 的 依然 是 原始 的 版 本 。 要 想 看 到 变更 效 来 ， 束 必 
须 重新 局 动 应 用 ， 这 当然 古 非 沼 个 方便 的 。 


羊 运 的 古 ， 有 一 种 方法 可 以 茶 用 缓存 。 我 们 所 需要 做 的 吏 是 将 相关 
的 绥 存 属性 设 略为 false。 表 2.3 列 出 每 种 模板 库 所 对 应 的 绥 存 属性 。 


表 2.3 ”局 用 /从 用 模 权 缓存 的 属性 


模板 局 用 绥 存 的 属性 


Groovy Templates spring.groovy.template.cache 
Thymeleaf spring.thymeleaf.cache 


默认 情况 下 ， 这 些 属 性 都 设置 成 了 true， 以 便于 局 用 缓存。 我 们 可 
以 将 缓存 属性 设置 为 false， 从 而 禁用 所 选 模板 引擎 的 缓存 。 例 如 ， 要 蔡 
用 Thymeleaf 绥 存 ， 我 们 只 需要 在 application.properties 中 诬 加 如 下 这 行 代 
伺 : 


spring.thymeleaf.cache=false 





唯一 需要 注意 的 征 ， 在 将 应 用 部 普 到 生产 环 蒂 之 前 ， 一 定 要 删除 这 
一 行 代码 〈 或 者 将 其 设置 为 tue) 。 有 一 种 方法 是 将 该 属性 设置 到 
profile 中 〈 我 们 将 会 在 第 5 章 讨论 profile) 。 另 外 一 种 更 简单 的 方式 是 使 
用 Spring Boot 的 DevTools， 束 像 我 们 在 第 1 章 中 的 做 法 一 样 。DevTools 
提供 了 很 多 非常 有 用 的 开发 期 符 性 ， 其 中 有 一 项 功能 就 是 禁用 所 有 模板 
库 的 缓存 ， 但 是 在 应 用 部 署 的 时 候 DevTools 会 将 自身 禁用 掉 〈( 从 而 能 够 
重新 局 用 模板 缓存 ) 。 


2.6 ”小 结 


。 Spring 提 供 了 一 个 强大 的 Web 框 架 ， 名 为 Spring MVC， 能 够 用 来 为 
Spring 应 用 开 及 Web 前 端 。 

。 Spring MVC 古 基于 注解 的 ， 通 过 像 @RequestMapping、 

@GetMapping 和 人 @PostMapping 这 样 的 注解 来 后 用 请 求 处 理 方法 的 

声明 。 

大 多 数 的 请 求 处 理 方法 最 终 会 返回 一 个 视图 的 逻辑 名 称 ， 比 如 

Thymeleaf 模 板 ， 请 求 会 转发 到 这 样 的 视图 上 【同时 会 币 有 任意 的 

模型 数据 〉。 

Spring MVC 文 持 校 验 ， 这 是 授 过 Java Bean Validation API 和 

Validation API 的 实现 (如 Hibernate Validator) 完成 的 。 

对 于 没有 模型 数据 和 逻辑 处 理 的 HTTP GET 请 求 ， 可 以 使 用 视图 控 

制 | 帮 。 

除了 Thymeleaf 之 外 ，Spring 支 持 各 种 视图 方案 ， 包 括 FreeMarker、 

Groovy Templates 和 Mustache。 





[1] 如 果 你 想 更 深入 地 了 解 应 用 领域 ， 我 推荐 你 阅读 Eric Evans 的 《 领 


域 驱 动 设 计 》 (ISBN978-7-115-37675-6， 人 民 邮 电 出 版 社 出 版 〉。 


[2] 样式 表 的 内 容 与 我 们 的 讨论 无 天 ， 它 只 十 包含 了 让 配料 两 列 显 示 的 
样式 ， 避 免 出 现 一 个 很 长 的 配料 列表 。 


[3] 其 中 一 个 这 样 的 例外 情况 束 是 Thymeleaf 的 Spring Security 方 言 ， 我 
们 将 会 在 第 4 章 进 行 讨论 。 


第 3 草 ”使 用 数据 


。 使 用 Spring 的 JdbcTemplate 


。 使 用 SimpleJdbcInsert 皇 入 数据 


。 使 用 Spring Data 声 明 JPA repository 





大 多 数 应 用 程序 提供 的 不 仅仅 是 一 个 永 完 的 界面 ， 虽 然 用 户 界 面 可 
能 会 提供 一 些 与 应 用 程序 的 交互 ， 但 是 应 用 程序 和 静 态 Web 站 氮 的 区 别 
在 于 它 所 展现 和 存储 的 数据 。 


在 Taco Cloud 应 用 中 ， 我 们 需要 维护 配料 、taco 和 订单 的 信息 。 如 
果 没 有 数据 库 来 存储 信息 ， 那 么 这 个 应 用 在 第 2 章 的 基础 上 也 束 没 有 什 
么 进展 了 。 

在 本 章 中 ， 我 们 将 会 为 Taco Cloud 应 用 添加 对 数据 持久 化 的 支持 。 


首先 ， 我 们 会 使 用 Spring 对 JDBC (Java Database Connectivity)〉 的 支持 
来 消除 样板 式 代 人 码 。 随 后 ， 我 们 会 使 用 JPA (Java Persistence API) 重 写 


数据 repository， 进 一 步 消 除 更 多 的 代码。 
3.1 使 用 JDBC 读 取 和 写 入 数据 


几 十 年 以 来 ， 关 系 型 数据 库 和 SQL 一 直 是 数据 持久 化 领域 的 首选 方 
案 。 尺 官 近年 来 涌现 了 许多 可 选 的 数据 库 类 型 ， 但 是 关系 型 数据 库 依 然 
征 通 用 数据 存储 的 首选 ， 而 且 短 期 内 不 六 可 能 捍 动 它 的 地 位 。 


在 处 理 关 系 型 数据 的 时 候 ，Java 开 发 人 员 有 多 种 可 选 方案 ， 其 中 最 
弟 见 的 是 JDBC 和 JPA。Spring 同 时 支持 这 两 种 抽象 形式 ， 能 够 让 JDBC 
或 JPA 的 使 用 更 加 容易 。 在 本 方 中 ， 我 们 将 会 讨论 Spring 如 何 支 持 
JDBC， 然 后 会 在 3.2 节 讨论 Spring 对 JPA 的 文 持 。 


Spring 对 JDBC 的 支持 要 归功 于 JdbcTemplate 类 。JdbcTemplate 提 供 
了 一 种 特殊 的 方式 ， 通 过 这 种 方式 ， 开 及 人 员 在 对 关系 型 数据 库 执行 
SQL 操 作 的 时 候 能 够 避免 使 用 JDBC 时 营 见 的 繁 文 缠 节 和 样板 式 代 人 码 。 


为 了 更 好 地 理解 JdbcTemplate 的 功能 ， 我 们 首先 看 一 个 不 使 用 
JdbcTemplate 的 样 例 ， 看 一 下 如 何在 Java 中 执行 一 个 简单 的 查询 ， 如 程 
序 清单 3.1 所 示 。 


程序 清单 3.1 不 使 用 JdbcTemplate 碍 询 数据 库 





QOverride 

public Ingredient findOne(String id) { 
Connection connection = null; 
PreparedStatement statement = null; 
ResultSet resultSet = null; 


try { 
connection = dataSource.getConnection(); 


statement = connection.prepareStatement( 
"select id, name, type from Ingredient where id=?"); 
statement.setString(1, id); 
resultSet = statement .executeQuery(); 
Ingredient ingredient = null,; 
if(resultSet.next()) { 
ingredient = new Ingredient( 
resultSet .getString("id"), 
resultSet.getString("name"), 
Ingredient.Type.valueOf(resultSet.getString("type"))); 
} 
return ingredient; 
catch (SQLException e) { 
// ??? What should be done here 3»3?? 
} finally 1{ 
if (resultSet != null) { 
try 1{ 
resultSet.closel(); 
} catch (SQLException e) {} 


一 


if (statement != null) { 


try 1{ 
statement.closel(); 


} catch (SQLException e) {} 
if (connection != null) { 


try 1{ 
connection.close() ; 


} catch (SQLException e) {} 
} 


return null; 


} 


我 癌 你 傈 证， 在 程序 清单 3.1 中 存在 查询 数 据 库 获取 配料 的 那 几 行 
代码 ， 但 我 敢 衣 定 你 很 难 在 JDBC 代 码 段 中 将 这 个 查询 找 出 来 ， 它 和 梓 创 
建 连接 、 创 建 语句 以 及 关闭 连接 、 语 句 和 结果 集 的 清理 功能 完全 包围 了 
起 来 。 


在 创建 连接 、 创 建 语句 或 执行 租 询 的 时 候 ， 可 能 会 出 现 很 多 错误 。 
这 如 要 求 我 们 捕获 SQLException， 它 对 于 找 出 哪里 出 现 了 问题 或 如 何 解 


次 问题 可 能 有 所 帮助 ， 也 可 能 坚 无 用 处 。 


SQLException 是 一 个 检查 型 民利 ， 它 需要 在 catch 代 码 块 中 进行 处 
理 。 但 是 ， 对 于 第 见 的 问题 ， 如 创建 到 数据 库 的 连接 失败 或 者 输入 的 得 
询 有 错误 ， 在 catch 代 码 块 中 是 无 法 解决 的 ， 并 且 有 可 能 要 继续 抛 出 以 便 
于 上 游 进行 处 理 。 作 为 对 比 ， 我 们 看 一 下 使 用 JdbcTemplate 的 方式 ， 如 
程序 清单 3.2 所 示 。 


程序 清单 3.2 ”使 用 JdbcTemplate 查 询 数据 库 


private JdbcTemplate Jdbc ; 


QOverride 
public Ingredient findOne(String id) { 
return jdbc.queryForObject( 
"select id, name, type from Ingredient where id=?",， 
this::mapRowToIngredient, id); 


} 


private Ingredient mapRowToIngredient(ResultSet rs, int rowNum) 
throws SQLException { 
return new Ingredient( 
rs.getString("id"), 
rs.getSstring("name"), 
Ingredient.Type.valueOf(rs.getString("type"))); 





程序 清单 3.2 中 的 代码 显然 要 比 程序 清 单 3.1 中 的 原始 JDBC 示 例 人 简单 
多 。 这 里 没有 创建 任何 的 连接 和 语句 。 而 且 ， 在 方法 完成 之 后 不 需要 
对 这 些 对 象 进行 清理 。 最 后 ， 这 里 也 没有 任何 catch 代 码 块 中 无 法 处 理 的 
弄 利 。 剩 下 的 代码 仅仅 关注 执行 租 询 〈 调 用 JdbcTemplate 的 
queryForObject0 ) 和 将 结果 映射 到 ngredient 对 象 〈 在 
mapRowToIngredient() 方 法 中 ) 上 。 


= 
村 


程序 清单 3.2 中 的 代码 仅仅 是 在 Taco Cloud 应 用 中 使 用 JdbcTemplate 
持久 化 和 读 取 数据 的 一 个 请 段 。 接 下 来 ， 我 们 独 手 实现 让 应 用 程序 文 持 
JDBC 持 入 化 的 下 一 个 步骤 。 我 们 首先 要 对 领域 对 象 进 行 一 些 调 整 。 


3.1.1 调整 领域 对 象 以 适应 持久 化 


在 将 对 象 持 久 化 到 数据 库 的 时 候 ， 通 第 最 好 有 一 个 字段 作为 对 象 的 
唯一 标识 。Ingredient 类 现在 已 经 有 了 一 个 id 字 段 ， 但 是 我 们 还 需要 将 id 
字段 添加 到 Taco 和 Order 类 中 。 


除 此 之 外 ， 记 录 Taco 和 Order 是 何 时 创建 的 可 能 会 非常 有 用 。 上 所 
以 ， 我 们 还 会 为 每 个 对 象 深 加 一 个 字段 来 捕获 它 所 创建 的 日 期 和 时 间 。 
程序 清单 3.3 展 现 了 Taco 类 中 新 增 的 id 和 createdAt 字 段 。 


程序 清单 3.3 ”为 Taco 类 添加 ID 和 时 间 惟 字段 


@Data 
public class Taco 1{ 


private Long id; 


private Date createdAt ; 





因为 我 们 使 用 Lombok 在 运行 时 生成 访问 器 方法 ， 所 以 在 这 里 只 需 
要 声明 id 和 createdAt 属 性 就 可 以 了 。 在 运行 时 ， 它 们 都 会 有 对 应 的 getter 
和 和 setter 方 法 。 类 似 的 变更 还 需要 应 用 到 Order 类 上 上 ， 如 下 所 示 : 


@Data 
public class Order { 


private Long id; 


private Date placedAt; 





同样 ，Lombok 会 目 动 生 成 访问 各 方法 ， 所 以 这 是 Order 类 的 唯一 变 
更 〈 如 果 因 为 某 种 原因 你 无 法 使 用 Lombok， 就 需要 自行 编写 这 些 方法 
J 


现在 ， 我 们 的 领域 类 已 经 为 持久 化 做 好 了 准备 。 接 下 来 ， 我 们 看 一 
下 该 如 何 使 用 JdbcTemplate 实 现 数据 库 的 读 取 和 写 入 。 


3.1.2 ”使 用 JdbcTemplate 


在 开始 使 用 JdbcTemplate 之 前 ， 我 们 需要 将 它 诬 加 到 项 目的 区 路 径 
中 。 这 一 点 非常 容易 ， 只 需要 将 Spring Boot 时 JDBC starter 依 顿 琴 加 到 构 
建文 件 中 束 可 以 了 : 


<dependency> 
<groupId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-jdbc</artifactId> 
</dependency> 





我 们 还 需要 一 个 存储 数据 的 数据 库 。 对 于 开 友 来 说 ， 骨 入 式 的 数据 
库 融 足够 了。 我 比较 喜欢 H2 租 入 却 数 据 库 ， 所 以 我 会 将 如 下 的 依赖 琴 
加 到 构建 文件 中 : 


<dependency> 
<groupId>com.h2database</groupId> 


<artifactId>h2</artifactId> 
<scope>runtime</scope> 
</dependency> 





随后 ， 你 将 会 看 到 如 何 配置 应 用 以 使 用 外 部 的 数据 库 ， 现 在 我 们 看 
一 下 如 何 编号 获取 和 保存 mgredient 数 据 的 repository。 


定义 JDBC repository 


我 们 的 Ingredient repository 需 要 完成 如 下 操作 : 


。 得 询 所 有 的 配料 信息 ， 将 它们 放 到 一 个 Ingredient 对 象 的 集合 
。 根据 id， 和 三 询 单个 mgredient; 
。 保存 Ingredient 对 象 。 


如 下 的 IngredientRepository 搁 口 以 方法 声明 的 方式 定义 了 3 个 操作 : 


package tacos.data; 

import tacos.Ingredient, 

public interface IngredientRepository { 
Iterable<Ingredient> findAll(); 


Ingredient findOne(String id); 


Ingredient save(Ingredient ingredient); 





尽管 该 接口 敏锐 捕捉 到 了 配料 repository 都 需要 做 些 什 么 ， 但 是 我 们 
依然 需要 编写 一 个 IngredientRepository 实 现 ， 使 用 JdbcTemplate 来 查询 数 


据 库 。 程 序 清单 3.4 展 示 了 编写 该 实现 的 第 一 步 。 
程序 清单 3.4 开始 使 用 JdbcTemplate 编 写 配 料 repository 


package tacos .data; 


import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.Jjdbc.core.JdbcTemplate,; 

Import org.springframework.JjJdbc.core.RowMapper.; 

Import org.springframework.stereotype.Repository; 


import tacos.Ingredient,; 


QRepository 
public class JdbcIngredientRepository 
implements IngredientRepository 1{ 


private JdbcTemplate Jdbc ; 


QAutowired 

public JdbcIngredientRepository(JdbcTemplate jdbc) { 
this.jdbc = jdbc; 

} 





我 们 可 以 看 到 ，JdbcIngredientRepository 洪 加 了 @Repository 注 解 。 
Spring 定义 了 一 系列 的 构造 型 〈stereotype) 注 骨 ，@Repository 是 其 中 之 
一 ， 其 他 注解 还 包括 @Controller 和 @Component。 为 
JdbcImgredientRepository 深 加 @Repository 注 解 之 后 ，Spring 的 组 件 扫描 
瓯 会 目 动 用 现 它 ， 并 且 会 将 其 初始 化 为 Spring 应 用 上 下 文中 的 bean。 


当 Spring 创 建 JdbcIngredientRepository bean 的 时 候 ， 它 会 通过 
@Autowired 标 注 的 构造 器 将 JdbcTemplate 注 入 进来 。 这 个 构造 器 将 
JdbcTemplate 赋 值 给 一 个 实例 变量 ， 这 个 变量 会 被 其 他 方法 用 来 执行 数 


据 库 租 询 和 插入 操作 。 说 到 其 他 的 这 些 方 法 ， 让 我 们 先 看 一 下 findAll0) 
和 findOne0O 的 实现 ， 如 程序 清单 3.5 所 示 。 


程序 清单 3.5 ”使 用 JdbcTemplate 丛 询 数据 库 


QOverride 
public Iterable<Ingredient> findAll() { 
return jdbc.query("select id, name, type from Ingredient", 
this::mapRowToIngredient ) ; 


} 


QOverride 
public Ingredient findOne(String id) { 
return jdbc.queryForObject( 
"select id, name, type from Ingredient where id=?",， 
this::mapRowToIngredient, id); 


} 


private Ingredient mapRowToIngredient(ResultSet rs, int rowNum) 
throws SQLEXception { 
return new Ingredient( 
rs.getString("id"), 
rs.getString("name" ), 
Ingredient.Type.valueOf(rs.getString("type" ))); 





findAll() 和 findOne() 以 相同 的 方式 使 用 了 JdbcTemplate。findAll0 方 
法 预期 返回 一 个 对 象 的 集合 ， 它 使 用 了 JdbcTemplate 的 query(0) 方 法 。 
query0O 会 接受 要 执行 的 SQL 以 及 Spring RowMapper 的 一 个 实现 〈 用 来 将 
结 采 集中 的 每 行 数 据 映 射 为 一 个 对 象 ) 。guery 0 方法 还 能 以 最 终 参 数 的 
形 陈 接收 得 询 中 所 需 的 任意 参数 。 但 是 ， 在 本 例 中 ， 我 们 不 需要 任何 参 
数 。 


findOne() 方 法 预期 只 会 返回 一 个 Ingredient 对 象 ， 所 以 它 使 用 了 
JdbcTemplate 的 queryForObjectO 方 法 ， 而 不 是 query(0) 方 法 。 


queryForObjectO 方 法 的 运行 方式 和 query0 非 常 类 似 ， 只 不 过 它 只 返回 一 
个 对 象 ， 而 不 是 对 象 的 List。 在 本 例 中 ， 它 接受 要 执行 的 得 询 、 
RowMapper 以 及 要 获取 的 Ingredient 的 id， 访 id 会 蔡 换 查询 中 的 “?”。 


如 程序 清单 3.5 所 示 ，findAll0 和 findOne() 中 的 RowMapper 参 数 都 是 
通过 对 mapRowTolIngredient() 的 方法 引用 指定 的 。 在 使 用 JdbcTemplate 的 
时 候 ，Java 8 的 方法 引用 和 lambda 表 达 式 非常 便利 ， 它 们 能 够 玲 代 注 式 
的 RowMapper 实 现 。 但 是 ， 如 果 因 为 菏 种 原因 ， 你 想 要 或 者 必须 使 用 显 
式 RowMapper， 那 么 如 下 的 findOne() 实 现 将 阐述 该 如 何 控 照 这 种 方式 进 
行 编 号 。 

QOverride 
public Ingredient findOne(String id) { 
return jdbc.queryForObject( 
"select id, name, type from Ingredient where id=?",， 
new RowMapper<Ingredient>() { 


public Ingredient mapRow(ResultSet rs, int rowNum) 
throws SQLException { 


return new Ingredient( 
rs.getString("id"), 
rs.getString("name"), 
Ingredient.Type.valueOf(rs.getString("type"))); 





从 数据 库 中 证 取 数 据 只 是 问题 的 一 部 分 。 在 有 些 情况 下 ， 我 们 必须 
移 将 数据 写 入 数据 库 ， 这 样 才 能 进行 谈 取 。 上 所 以 ， 我 们 接 下 来 看 一 下 议 
如 何 实现 save0) 方 法 。 


插入 一 行 数据 


JdbcTemplate 的 update0) 方 法 可 以 用 来 执行 回 数 据 库 中 与 入 或 更 新 数 
据 的 得 询 语句 。 如 程序 清单 3.6 所 示 ， 它 可 以 用 来 将 数据 插入 到 数据 库 
中 。 


程序 清单 3.6 ”使 用 JdbcTemplate 插 入 数据 


QOverride 
public Ingredient save(Ingredient ingredient) { 
jdbc .update( 
"insert into Ingredient (id, name, type) values (?, ?, ?)", 


ingredient.getId()， 

ingredient.getName(), 

ingredient.getType().toSstring() ) ; 
return ingredient; 





} 


因为 在 这 里 不 需要 将 ResultSet 数 据 上 映射 为 对 象 ， 所 以 update0 方 法 要 
query0O 或 queryForObjectO 人 简单 得 多 。 它 只 需要 一 个 包含 竺 执行 SQL 的 
String 以 及 每 个 但 询 参 数 对 应 的 值 即 可 。 在 本 例 中 ， 俘 询 有 3 个 参数 ， 对 
应 save() 方 法 最 后 的 3 个 参数 ， 分 别 是 配料 的 d、 名 称 和 类 型 。 


JdbcIngredientRepository 编 号 完成 之 后 ， 我 们 束 可 以 将 其 注入 到 
DesignTacoController 中 了， 然后 使 用 它 来 提供 Ingredient 对 象 的 列表 ， 不 
用 再 使 用 便 编 码 的 值 〈 不 像 第 2 草 中 所 做 的 那样 〉。 修 改 后 的 
DesignTacoController 如 程序 清单 3.7 所 示 。 


程序 清单 3.7 在 控制 器 中 注入 和 使 用 repository 





@Controller 
@QRequestMapping("/design") 
@SessionAttributes("order") 

public class DesignTacoController { 


private final IngredientRepository ingredientRepo,; 


QAutowired 
public DesignTacoController(IngredientRepository ingredientRepo) 
this.ingredientRepo = ingredientRepo; 


} 


一 ~ 


Q@GetMapping 

public String showDesignForm(Model model) { 
List<Ingredient> ingredients = new ArrayList<>(); 
ingredientRepo.findAll().forEach(i -> ingredients.add(i)); 
Type[] types = Ingredient.Type.values(); 
for (Type type : types) { 

model.addAttribute(type.toSstring() .toLowerCase( )， 
filterByType(ingredients, type)); 

} 


return "design"; 


需要 注意 的 是 ，showDesignForm() 方 法 的 第 二 行 调 用 了 注入 的 
IngredientRepository 的 findAH0O 方 法 。findAl10 方 法 会 从 数据 库 中 获取 上 所 
有 的 配料 ， 并 将 它们 过 滤 成 不 同 的 类 型 ， 然 后 放 到 模型 中 。 


现在 ， 我 们 蕊 上 束 能 局 动 应 用 并 等 试 这 些 变 更 了 。 但 是 ， 在 使 用 但 
询 语 句 从 Ingredient 表 中 读 取 数据 之 前 ， 我 们 需要 先 创 建 这 个 表 并 填充 一 
些 配 料 数 据 。 


3.1.3 ”定义 模式 和 预 加 载 数据 


除了 Ingredient 表 之 外 ， 我 们 还 需要 其 他 的 一 些 表 来 保存 订 早 和 设计 
寺 轧 。 图 3.1 摘 述 了 我 们 所 需要 的 表 以 及 这 些 表 之 间 的 关联 关系 。 


Taco_Order_Tacos 

Taco_Order tacoOrder: bigint 
id: identity taco: bigint 
deliveryName: varchar Taco 
deliveryStreet: varchar eg , 
deliveryCity: varchar Ey 
deliveryState: varchar es Mado 
deliveryZip: varchar createdAt: timestamp 
ccNumber: varchar Taco_Ingredients 
ccExpiration: varchar 
ccCVV: varchar 
placedAt: timestamp 


taco: bigint 
ingredient: varchar 


Ingredient 


id: varchar 
name: varchar 
type: varchar 





图 3.1 ”Taco Cloud 模 式 的 表 
图 3.1 中 的 表 主 要 实现 如 下 月 的。 


。 Ingredient: 保存 配料 信息 。 

。 Taco: 你 和 存 taco 设 计 相 天 的 信息 。 

。Taco_Ingredients: Taco 中 的 每 行 数据 都 对 应 一 行 或 多 行 ， 将 taco 和 和 
与 之 相关 的 配料 映射 在 一 起 。 

。 Taco_Order: 你 存 必要 的 订单 细节 。 

。Taco Order Tacos: Taco Order 中 的 每 行 数 据 都 对 应 一 行 或 多 行 ， 
将 订单 和 与 之 相关 的 taco 映 味 在 一 起 。 


程序 清单 3.8 展 示 了 创建 表 的 SQL。 


程序 清单 3.8 定义 Taco Cloud 的 模式 





create table if not exists Ingredient ( 
id varchar(4) not null, 

name varchar(25) not null, 

type varchar(16) not null 


); 


create table if not exists Taco ( 
id identity, 
name Varchar(56) not null, 
createdAt timestamp not null 


D3 


create table if not exists Taco Ingredients ( 
taco bigint not null, 
ingredient varchar(4) not null 


3 


alter table Taco Ingredients 
add foreign key (taco) references Taco(id); 
alter table Taco Ingredients 
add foreign key (ingredient) references Ingredient(id); 


create table if not exists Taco Order ( 
id identity, 

deliveryName varchar(560) not null, 
deliveryStreet Varchar(56) not null, 
deliveryCity varchar(56) not null, 
deliveryState varchar(2) not null, 
deliveryZip varchar(16) not null, 
ccNumber varchar(16) not null, 
ccExpiration varchar(5) not null, 
cCCVV varchar(3) not null, 
placedAt timestamp not null 


)3 


create table if not exists Taco Order Tacos ( 
tacoOrder bigint not null, 
taco bigint not null 


); 
alter table Taco Order Tacos 
add foreign key (tacoOrder) references Taco Order(id); 


alter table Taco Order Tacos 
add foreign key (taco) references Tacol(id); 


现在 ， 最 大 的 问题 是 将 这 些 模式 定义 放 在 什么 地 方 。 实 际 上 ， 
Spring Boot 回 答 了 这 个 问题 。 


如 未 在 应 用 的 根 关 路 径 下 存在 名 为 schema.sql 的 文件 ， 那 么 在 应 用 


局 动 的 时 候 将 会 基于 数据 库 执 行 这 个 文件 中 的 SQL。 上 所 以 ， 我 们 需 
程序 清单 3.8 中 的 内 容 保存 为 名 为 schema.sql 的 文件 并 放 
到 “src/main/resources” 文 件 严 下 。 


要 将 


我 们 可 能 还 和 希 刻 在 数据 库 中 预 加 载 一 些 配料 数据 。 圣 运 的 是 ， 
Spring Boot 还 会 在 应 用 局 动 的 时 候 执 行 根 茯 路 径 下 名 为 data.sql 的 文件 。 
所 以 ， 我 们 可 以 使 用 程序 清单 3.9 中 的 插入 语句 为 数据 库 加 载 配 料 数 
据 ， 并 将 其 保存 到 “src/main/resources/data.sql” 文 件 中 。 


程序 清单 3.9” 预 加 载 数 据 库 


from 
from 
from 
from 


delete 
delete 
delete 
delete 


Taco Order Tacos ; 
Taco Ingredients; 
Taco; 

Taco Order; 

from 


delete Ingredient; 


insert 


insert 


insert 


insert 


insert 


insert 


insert 


insert 


insert 


insert 


into 


into 


into 


into 


into 


into 


into 


into 


into 


into 


Ingredient 
values 
Ingredient 
values 
Ingredient 
values 
Ingredient 
values 
Ingredient 
values 
Ingredient 
values 
Ingredient 
values 
Ingredient 
values 
Ingredient 
values 
Ingredient 
values 


(id, name, type) 
('FLTO", "Flour Tortilla', 
(id, name, type) 

('COTO', 'Corn Tortilla', 
(id, name, type) 
('GRBF' , 'Ground Beef ' ， 
(id, name, type) 
('CARN' , 'Carnitas', 
(id, name, type) 
('TMTO", "Diced Tomatoes ' ， 
(id, name, type) 
('LETC', "Lettuce ' ， 
(id, name, type) 
('CHED' ， 'Cheddar',， 
(id, name, type) 
('JACK', 'Monterrey Jack', 
(id, name, type) 
('SLSA'", 'Salsa', 
(id, name, type) 
('SRCR', 'Sour Cream', 


'NRAP ' ); 
'NRAP ' ) ; 
'PROTEIN ' ) ; 
'PROTEIN ' ) ; 
'VEGGIES ' ) ; 
'VEGGIES ' ) ; 
'CHEESE ' ) ; 


'CHEESE ' ) ; 


'SAUCE ' ) ; 


'SAUCE ' ) ; 





尺 官 我 们 目前 只 为 配料 数据 编写 了 一 个 repository， 但 是 你 依然 可 以 
将 Taco Cloud 应 用 局 动 起 来 并 访问 设计 页 面 ， 看 一 下 
JdbcIngredientRepository 的 实际 功能 。 尽 可 以 去 答 试 一 下 ! 当 你 答 试 完 
回来 的 时 候 ， 我 们 将 会 编写 Taco、Order 和 数据 持久 化 的 repository。 


3.1.4 ”搬入 数据 


我 们 已 经 粗略 看 到 了 如 何 使 用 JdbcTemplate 将 数据 写 入 到 数据 库 
中 。JdbcIngredient Repository 的 Save0) 方 法 使 用 JdbcTemplate 的 updateO) 方 
法 将 Ingredient 对 象 保存 到 了 数据 库 中 。 


尽管 这 是 一 个 非常 好 的 起 步 样 例 ， 但 是 它 过 于 简单 了 。 你 马上 将 会 
看 到 保存 数据 可 能 会 比 JdbcIngredientRepository 更 加 复杂 。 借 助 
JdbcTemplate， 我 们 有 以 下 两 种 保存 数据 的 方法 。 


。 直接 使 用 update() 方 法 。 
。 使 用 SimpleJdbcInsert 包 装 器 类 。 


让 我 们 首先 看 一 下 在 持久 化 需求 比 保存 Ingredient 更 为 复杂 的 情况 下 
该 如 何 使 用 update0) 方 法 。 


使 用 JdbcTemplate 保 存 数 据 


现在 ，taco 和 order 的 repository 唯 一 害 要 做 的 事情 束 古 你 存 对 应 的 对 
象 。 为 了 保存 Taco 对 象 ，TacoRepository 声 明了 一 个 save(0) 方 法 : 


| package tacos .data 


import 七 acos .Taco 


public interface TacoRepository 1{ 


Taco save(Taco design); 





与 之 类 似 ，OrderRepository 也 声明 了 一 个 save() 方 法 : 


package tacos.data; 
Import tacos.Order; 


public interface OrderRepository { 


Order save(Order order); 


} 





看 起 来 非常 向 单 ， 对 吧 ? 但 是 ， 保 存 taco 的 时 候 需 要 同时 将 与 该 
taco 关 联 的 配料 保存 到 Taco_Ingredients 表 中 。 与 之 类 似 ， 保 存 订单 的 时 
候 ， 需 要 同时 将 与 该 订单 关联 的 taco 傈 存 到 Taco_Order_Tacos 表 中 。 这 
样 看 来 ， 体 存 taco 和 订单 焉 会 比 体 存 配料 更 困难 一 些 。 


为 了 实现 TacoRepository， 我 们 需要 用 save0 方 法 首先 保存 必要 的 
taco 设 计 细 和 《〈 比 如， 名称 和 创建 时 间 ) ， 然 后 对 Taco 对 象 中 的 每 种 配 
料 都 插入 一 行 数据 到 Taco_Ingredients 中 。 程 序 清单 3.10 展 示 了 完整 的 


JdbcTacoRepository 类 。 


程序 清单 3.10 ”使 用 JdbcTemplate 实 现 TacoRepository 





package tacos.data; 


Import java.sql.Timestamp; 
import JjJava.sql.Types; 


import 
import 


import 
import 
import 
import 
import 
import 


import 
import 


Java.util.Arrays; 
Java.util.Date,; 


org.springframework. 
org.springframework. 
org.springframework. 
org.springframework. 
org.springframework. 
org.springframework. 


tacos.Ingredient; 
tacos.Taco,; 


QRepository 
public class JdbcTacoRepository implements TacoRepository { 


jdbc. 
jdbc. 
jdbc. 
jdbc. 
jdbc. 


core.JdbcTemplate; 
core.PreparedSstatementCreator ; 
core.PreparedStatementCreatorFactory; 
suUupport .GeneratedkeyHolder ; 
support.KeyHolder; 


stereotype.Repository; 


private JdbcTemplate Jdbc ; 


public JdbcTacoRepository(JdbcTemplate jdbc) { 
this.jdbc = jdbc; 


} 


QOverride 
public Taco save(Taco taco) { 
long tacoId = saveTacoInfo(Ctaco ) ; 
taco.setId(tacoId ) ; 
for (Ingredient ingredient 


} 


return 七 aco ; 


} 


: taco.getIngredients()) { 
saveIngredientToTaco(ingredient, tacolId); 


private long saveTacoInfo(Taco taco) { 
taco.setCreatedAt (new Date() ) ; 


PreparedStatementCreator psc 


new PreparedStatementCreatorFactory( 


"insert into Taco (name, createdAt) values (?, ?)",， 


Types .VARCHAR, Types.TIMESTAMP 
) .newPreparedStatementCreator( 


Arrays.asList( 


taco.getName( ) ， 


new Timestamp(taco.getCreatedAt() .getTime()))); 


KeyHolder keyHolder = new GeneratedKeyHolder() ; 
jdbc.update(psc，KkeyHolder ) ; 


return KeyHolder.getKey() .LongValue( ) ; 


} 


private void saveIngredientToTaco( 
Ingredient ingredient, long tacoId) { 
jdbc .updatel( 
"insert into Taco Ingredients (taco, ingredient) " + 
"Values (?, ?)",， 
tacoId, ingredient.getId()); 





我 们 可 以 看 到 ，save() 方 法 首先 调用 了 私有 有 的 saveTacolInfo() 方 法 ， 
然后 使 用 该 方法 所 返回 的 taco ID 来 调用 saveIngredientToTaco()， 最 后 的 
这 个 方法 会 你 存 每 种 配料 。 这 里 的 问题 在 于 saveTacoInfo() 方 法 的 细节 。 


当 同 Taco 中 插入 一 行 数 据 的 时 候 ， 我 们 需要 知道 数据 库 生 成 的 ID， 
这 样 我 们 才 可 以 在 每 个 配料 信息 中 引用 它 。 保 存 配料 数据 时 所 使 用 的 
update() 方 法 无 法 帮助 我 们 得 到 所 生成 的 DD， 所 以 在 这 里 我 们 需要 一 个 
不 同 的 update0 方 法 。 


这 里 的 update0) 方 法 需要 接受 一 个 PreparedStatementCreator 和 一 个 
KeyHolder。KeyHolder 将 会 为 我 们 提供 生成 的 taco ID 。 但 是 ， 为 了 使 用 
该 方法 ， 我 们 必须 还 要 创建 一 个 PreparedStatementCreator。 


从 程序 清单 3.10 中 可 以 看 到 ， 创 建 PreparedStatementCreator 并 不 简 
单 。 首 先 需 要 创建 PreparedStatementCreatorFactory， 并 将 我 们 要 执行 的 
SQL 传递 给 它 ， 同 时 还 要 包含 每 个 得 询 参数 的 类 型 。 随 后 ， 需 要 调用 该 
工厂 类 有 的 newPreparedStatementCreator() 方 法 ， 并 将 查询 参数 所 需 的 值 传 
圳 进 来 ， 这 样 才 能 生成 一 个 PreparedStatementCreator。 


有 了 PreparedStatementCreator 之 后 ， 我 们 殉 可 以 调用 update(0) 方 法 
了 ， 并 且 需 要 将 PreparedStatementCreator 和 KeyHolder 〈 在 本 例 中 ， 也 惑 
tan 的 实例 ) 传递 进来 。updateO 调 用 完成 之 后 ， 我 们 
驶 可 以 通过 keyHolder.getKey0O.longValue0O 返 回 taco 的 ID。 


回 到 save0 方 法 ， 接 下 来 我 们 会 轮 询 Taco 中 的 每 个 mgredient， 并 调 
用 SaveIngredient ToTaco()。savelIngredientToTaco() 使 用 更 简单 的 update() 
形式 来 将 对 配料 的 引用 你 存 到 Taco_Ingredients 表 中 。 


对 于 TacoRepository 来 说 ， 剩 下 的 事情 束 古 将 它 注 入 到 
DesignTacoController 中 ， 并 在 保存 taco 的 时 候 调 用 它 。 程 序 清 单 3.11 展 
现 了 注入 repository 所 需 的 必要 变更 。 


程序 清单 3.11 注入 并 使 用 TacoRepository 


QController 
@QRequestMapping("/design") 
QSessionAttributes("order") 

public class DesignTacoController { 


private final IngredientRepository ingredientRepo,; 


private TacoRepository designRepo; 


QAutowired 
public DesignTacoController( 
IngredientRepository ingredientRepo, 
TacoRepository designRepo) { 
this.ingredientRepo = ingredientRepo; 
this.designRepo = designRepo; 


} 





正如 我 们 所 看 到 的 ， 构 造 器 能 够 同时 接受 IngredientRepository 和 
TacoRepository 对 象 。 访 构造 右 将 得 到 的 对 象 赋值 给 实例 变量 ， 这 样 它 
们 就 可 以 在 showDesignForm() 和 processDesign() 中 使 用 了 。 


谈 到 processDesign() 方 法 ， 它 的 变更 要 比 showDesignForm() 的 变更 
更 大 一 些 。 程 序 清单 3.12 展 现 了 新 的 processDesign() 方 法 。 


程序 清单 3.12 ”保存 taco 设 计 并 将 它们 链接 全 订单 页 面 


@Controller 
@QRequestMapping("/design") 
QSessionAttributes("order") 

public class DesignTacoController { 


@QModelAttribute(name = "order") 
public Order order() { 
return new Order(); 


} 


QModelAttribute(name = "taco") 
public Taco taco() { 
return new Taco() ; 


} 


QPostMapping 

public String processDesign( 
@Valid Taco design, Errors errors, 
@QModelAttribute Order order) { 


if (errors.hasErrors()) { 
return "design"; 


} 


Taco saved = designRepo.save(design); 
order.addDesign(saved ) ; 


return “redirect:/orders/current"; 


| } | 


在 程序 清单 3.12 中 ， 你 首先 关注 到 的 事情 可 能 是 
DesignTacoController 类 添加 了 @SessionAttributes("order) 注 解 ， 并 且 它 
有 一 个 新 的 市 有 @ModelAttribute 注 解 的 方法 ， 即 order() 方 法 。 与 taco0) 
方法 类 似 ，order() 方 法 上 的 @ModelAttribute 注 解 能 够 确保 会 在 模型 中 创 
建 一 个 Order 对 象 。 但 是 与 模型 中 的 Taco 对 象 不 同 ， 我 们 需要 订单 信息 
在 多 个 请 求 中 都 能 出 现 ， 这 样 的 话 我 们 残 能 创建 多 个 taco 并 将 它们 添加 
到 该 订单 中 。 类 级 别 的 @SessionAttributes 能 够 指定 模型 对 象 ( 如 订单 属 
性 ) 要 你 存在 session 中 ， 这 样 才 能 跨 请 求 使 用 。 


对 taco 设 计 的 处 理 位 于 processDesign() 方 法 中 。 该 方法 接受 Order 对 
象 作 为 参数 ， 同 时 还 包括 Taco 和 Errors 对 象 。Order 参 数 币 有 
@ModelAttribute 注 解 ， 表 明 它 的 值 应 该 是 米 目 模型 的 ，Spring MVC 不 
会 答 试 将 请 求 参 数 绑 定 到 它 上 面 。 


在 检查 完 校 验 错误 之 后 ，processDesign() 使 用 注入 的 TacoRepository 
来 保存 taco。 然 后 ， 它 将 Taco 对 象 保 存 到 session 里 面 的 Order 中 。 


实际 上 ， 在 用 户 完成 操作 并 提交 订单 表单 之 前 ，Order 对 象 会 一 直 
保存 在 session 中 ， 并 没有 保存 到 数据 库 中 。 到 时 ，OrderController 需 要 
调用 OrderRepository 的 实现 来 保存 订 早 。 接 下 来 ， 我 们 编写 这 个 实现 


类 。 


使 用 SimpleJdbcInsert 插 入 数据 


在 前 文中 提 到 ， 保 存 taco 的 时 候 不 仅 要 将 taco 的 名 称 和 创建 时 间 伍 
存 到 Taco 表 中 ， 还 需要 将 该 taco 所 引用 的 配料 傈 存 到 Taco_Ingredients 表 
中 。 此 时 ， 需 要 我 们 知道 Taco 的 ID， 而 这 征 通 过 KeyHolder 和 
PreparedStatementCreator 获 取 的 。 


在 保存 订 单 的 时 候 ， 存 在 类 似 的 情况 。 我 们 不 仅 要 将 订单 数据 保存 
到 Taco_Order 表 中 ， 还 要 将 订单 对 每 个 taco 的 引用 保存 到 
Taco_Order_Tacos 表 中 。 但 是 ， 在 这 里 ， 我 们 不 再 使 用 烦 开 的 
Rs 而 是 引入 SimpleJdbcInsert， 这 个 对 象 对 
JdbcTemplate 进 行 了 包装 ， 能 够 更 容易 地 将 数据 插入 到 表 中 。 


首先 ， 我 们 要 创建 一 个 JdbcOrderRepository， 它 是 OrderRepository 
的 实现 。 但 在 编写 save() 方 法 的 实现 之 前 ， 我 们 先天 注 一 下 构造 砷 ， 在 
构造 右 中 我 们 会 创建 SimpleJdbcInsert 的 两 个 实例 ， 分 别 用 来 把 值 插入 到 
Taco_Order 和 Taco_Order Tacos 表 中 。 程 序 清单 3.13 展 现 了 
JdbcOrderRepository 〈 疝 不 包含 save0 方 法 ) 。 


程序 清单 3.13 ”通过 JdbcTemplate 创 建 SimpleJdbcInsert 





package tacos .data; 


import JjJava.util.Date,; 
import JjJava.util.HashMap; 
import JjJava.util.List,; 
import Java.util.Map; 


import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.Jdbc.core.JdbcTemplate,; 
import org.springframework.Jdbc.core.simple.SimpleJdbcInsert; 
Import org.springframework.stereotype.Repository; 


Import com.fasterxml.Jackson.databind.ObjectMapper.:; 


Import tacos.Taco; 
Import tacos .Order; 


QRepository 
public class JdbcOrderRepository implements OrderRepository 1{ 


private SlimpleJdbcInsert orderInserter ; 
private SlimpleJdbcInsert orderTacoInserter ; 
private ObjectMapper obJjectMapper ; 
QAutowired 
public JdbcOrderRepository(JdbcTemplate jdbc) { 
this.orderInserter = new SimpleJdbcInsert(jdbc) 
.withTableName("Taco Order") 
.USingGeneratedKeyColumns("id"); 
this.orderTacoInserter = new SimpleJdbcInsert(jdbc) 


.withTableName("Taco Order Tacos"); 
this.objectMapper = new ObjectMapper(); 


与 JdbcTacoRepository 类 似 ，JdbcOrderRepository 退 过 构造 右 将 
JdbcTemplate 注 入 进来 。 但 是 在 这 里 ， 我 们 没有 将 JdbcTemplate 直 接 赋 
给 实例 变量 ， 而 是 使 用 它 构 建 了 两 个 SimpleJdbcInsert 实 例 。 第 一 个 实例 
赋值 给 J 了 orderInserter 实 例 变 量 ， 配 置 为 与 Taco_Order 表 协作 ， 并 且 假 定 
id 属 性 将 会 由 数据 库 提供 或 生成 。 第 二 个 实例 赋值 给 了 orderTacoInserter 
实例 变量 ， 配 置 为 与 Taco_Order_Tacos 表 协作 ， 但 是 没有 声明 该 表 中 JID 
征 如 何 生成 的 。 


该 构造 右 还 创建 了 Jackson 中 ObjectMapper 类 的 一 个 实例 ， 并 将 其 赋 
值 给 一 个 实例 变量 。 尽 管 Jackson 的 初衷 是 进行 JSON 处 理 ， 但 是 你 很 快 
就 会 看 到 我 们 是 如 何 使 用 它 来 帮助 我 们 保存 订单 和 关联 的 taco 的 。 


现在 ， 我 们 看 一 下 save( 方 法 该 如 何 使 用 SimpleJdbcInsert 实 例 。 程 
序 清单 3.14 展 示 了 save() 方 法 以 及 一 些 私 有 方法 ， 其 中 save( 方 法 会 将 实 
际 的 工作 委托 给 这 些 私有 方法 。 


程序 清单 3.14 ”使 用 SimpleJdbcImsert 插 入 数据 


QOverride 

public Order save(Order order) { 
order.setPplacedAt (new Date()); 
long orderId = saveOrderDetails(order); 
order.setId(orderId); 
List<Taco> tacos = order.getTacos(); 
for (Taco taco : tacos) { 

saveTacoToOrder(taco, orderId); 


} 


return order ; 


} 


private long saveOrderDetails(Order order) { 
@SuppressWarnings("unchecked") 
Map<String, Object> values = 
objectMapper .convertValue(order, Map.class); 
values.put("placedAt"，order .getPlacedAt() ) ; 


long orderId = 
orderInserter 
.exXecuteAndReturnKey(values) 
.longValuel( ); 
return orderId ; 


} 


private void saveTacoToOrder(Taco taco, long orderId) { 
Map<String, Object> values = new HashMap<>() ; 
values.put("tacoOrder", orderId); 
values.put("taco", taco.getId()); 
orderTacoInserter.execute(values); 





Save() 方 法 实际 上 没有 保存 任何 内 容 ， 只 是 定义 了 你 存 Order 及 其 关 
联 的 Taco 对 象 的 流程 ， 并 将 实际 的 持久 化 任务 委托 给 了 


saveOrderDetails() 和 和 saveTacoToOrder()。 


SimpleJdbcInsert 有 两 个 非常 有 用 的 方法 来 执行 数据 插入 操作 : 
execute() 和 execute AndReturnKey()。 它 们 都 接受 Map<String, Object> 作 
为 参数 ， 其 中 Map 的 key 对 应 表 中 要 插入 数据 的 列 名 ， 而 Map 中 的 value 
对 应 要 插入 到 列 中 的 实际 值 。 


我 们 只 需 将 Order 中 的 值 复制 到 Map 的 条 目 中 融 能 很 容易 地 创建 一 个 
这 样 的 Map。 但 是 ，Order 央 很 多 属性 ， 这 些 属性 与 对 应 的 列 有 着 相同 的 
名 称 。 鉴 于 此 ， 在 saveOrderDetails() 中 ， 我 决定 使 用 Jackson 的 
ObjectMapper 及 其 convertValue0) 方 法 ， 以 便于 将 Order 转 换 为 MapL。 
Map 创 建 完 成 之 后 ， 我 们 将 Map 中 placedAt 条 目的 值 设 置 为 Order 对 象 
placedAt 属 性 的 仁 。 之 所 以 需要 这 样 做 ， 是 因为 ObjectMapper 会 将 Date 
属性 转换 为 Iong， 这 会 导致 与 Taco_Order 表 中 的 placedAt 字 段 不 车 容 。 


当 Map 中 准备 好 订单 数据 之 后 ， 我 们 束 可 以 调用 orderInserter 的 
executeAnd ReturnKey0 方 法 了 。 访 方法 会 将 订单 信息 保存 到 Taco_Order 
表 中 ， 并 以 Number 对 象 的 形式 返回 数据 库 生 成 的 D， 继 而 调用 
longValue() 方 法 将 返回 值 转换 为 long 类 型 。 


saveTacoToOrder() 方 法 要 简单 得 多 。 在 这 里 我 们 没有 使 用 
ObjectMapper 将 对 象 转换 为 Map， 而 是 直接 创建 了 一 个 Map 并 设置 对 应 
的 什 。 同 样 ，Map 的 key 与 表 中 的 列 名 对 应 。 我 们 只 需要 简单 地 调用 
orderTacoInserter 所 jexecute() 方 法 就 能 执行 插入 操作 了 。 


现在 ， 我 们 可 以 将 OrderRepository 注 入 到 OrderController 中 并 开始 使 


用 它 了。 程序 清单 3.15 展 示 了 完整 的 OrderController， 包 括 使 用 注入 的 
OrderRepository 相 天 的 变更 。 


程序 清单 3.15 ”在 OrderController 中 使 用 OrderRepository 


package tacos .Web ; 
import Javax.validation.Valid; 


Import org.springframework.stereotype.Controller.; 

import org.springframework.validation.Errors; 

Import org.springframework.web.bind.annotation.GetMapping; 

Import org.springframework.web.bind.annotation.PostMapping; 
import org.springframework.web.bind.annotation.RequestMapping; 
import org.springframework.web.bind.annotation.SessionAttributes; 
import org.springframework.web.bind.support.SessionStatus; 


Import tacos.Order; 
Import tacos.data.OrderRepository; 


@Controller 
@QRequestMapping("/orders") 
@QSessionAttributes("order") 
public class OrderController { 


private OrderRepository orderRepo ; 


public OrderController(OrderRepository orderRepo) { 
this.orderRepo = orderRepo ; 


} 


@QGetMapping("/current") 
public String orderForm() { 
return “orderForm'",; 


} 


QPostMapping 
public String processOrder(@Valid Order order, Errors errors, 
SessionStatus sessionStatus) { 
if (errors.hasErrors()) { 
return "orderForm"; 


} 


orderRepo.save(order ) ; 
sessionStatus.setCompletel( ) ; 


return “redirect:/";， 


} 


除了 将 OrderRepository 注 入 到 控制 天 中 ，OrderController 唯 一 明显 的 
变化 束 是 processOrder(0) 方 法 。 在 这 个 方法 中 ， 人 退 过 表单 提交 的 Order 对 
象 〈 同 时 也 是 session 中 持 有 的 Object 对 象 ) 会 通过 注入 的 
OrderRepository 的 Save0) 方 法 进行 保存 。 


订单 体 存 完成 之 后 ， 我 们 吏 不 需要 在 session 中 持 有 它 了 。 实 际 上 ， 
如 果 我 们 不 把 它 清理 挥 ， 那 么 订单 会 继续 你 留 在 session 中 ， 其 中 包括 与 
之 天 联 的 taco， 下 一 次 的 订单 将 会 从 旧 订 单 中 保存 的 taco 开 始 。 所 以 ， 
processOrder() 方 法 请 求 了 一 个 SessionStatus 参 数 ， 并 调用 了 它 的 
setComplete() 方 法 来 重 置 session 。 


所 有 JDBC 持 久 化 代码 已 经 束 绪 ， 现 在 我 们 可 以 启动 Taco Cloud 应 用 
并 进行 尝试 了 。 你 可 以 按照 日 己 的 意愿 创建 任意 数量 的 taco 和 订单 。 


你 可 能 会 友 现 ， 深 入 研究 一 下 数据 库 中 的 内 容 是 非常 有 帮助 的 。 我 
们 目前 使 用 H2 作 为 租 入 式 数 据 库 并 且 局 用 了 Spring Boot DevTools， 上 所 
以 我 们 可 以 在 浏览 器 中 访问 http://localhost:8080/h2-console 以 查看 H2 
Console。 使 用 献 认 的 凭证 应 该 束 可 以 进入 ， 但 是 你 需要 确 你 JDBC URL 
字段 设置 成 了 dbc:h2:mem:testdb。 登 录 之 后 ， 我 们 可 以 对 Taco Cloud 模 
式 下 的 表 执 行 任 意 的 但 询 。 


相对 于 普通 的 JDBC，Spring 的 JdbcTemplate 和 SimpleJdbcInsert 能 够 
极 大 地 简化 天 系 型 数据 库 的 使 用 。 但 是 ， 你 会 发 现 使 用 JPA 会 更 加 俐 


单 。 我 们 回顾 一 下 目 己 的 工作 内 容 ， 看 一 下 Spring Data 是 如 何 让 数据 持 
从化 变 得 更 简单 的 。 


3.2 ”使 用 Spring Data JPA 持 和 久 化 数据 


Spring Data 是 一 个 非常 六 的 伞 形 项 目 ， 由 多 个 子 项 目 组 成 ， 其 中 大 
多 数 子 项 目 剖 关注 对 不 同 的 数据 库 类 型 进行 数据 持久 化 。 比 较 法 行 的 几 
个 Spring Data 项 目 包 括 : 


。 Spring Data JPA: 基于 关系 型 数据 库 进 行 JPA 持 久 化 。 
。 Spring Data MongoDB: 持久 化 到 Mongo 文 档 数 据 库 。 
。 Spring Data Neo4j: 持久 化 到 Neo4j 图 数据 库 。 

。 Spring Data Redis: 持久 化 到 Redis key-value 存 储 。 

。 Spring Data Cassandra: 持久 化 到 Cassandra 数 据 库 。 


Spring Data 为 所有 项 目 提 供 了 一 项 最 有 趣 且 最 有 用 的 特性 ， 束 古 基 
于 repository 规 范 接口 目 动 生成 repository 的 功能 。 


要 了 解 Spring Data 征 如 何 运 行 的 ， 我 们 需要 重新 开始 ， 将 本 章 前 文 
基于 JDBC 的 repository 蔡 换 为 使 用 Spring Data JPA 的 repository。 首 先 ， 
我 们 需要 将 Spring Data JPA 洪 加 到 项 目的 构建 文件 中 。 


3.2.1 添加 Spring Data JPA 到 项 目 中 


Spring Boot 应 用 可 以 通过 JPA starter 来 添加 Spring Data JPA。 这 个 
starter 依 赖 不仅 会 引入 Spring Data JPA， 还 会 传递 性 地 将 Hibernate 作 为 


JPA 实 现 引 入 进来 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-data-jpa</artifactId> 
</dependency> 





如 采 你 想 要 使 用 不 同 的 卫 A 实 现 ， 那 么 至 少 需要 将 Hibernate 依 赖 排 
除 出 去 并 将 你 所 选择 的 JPA 库 包 售 进来 。 举 例 来 说 ， 如 采 想 要 使 用 
EclipseLink 来 蔡 代 Hibernate， 殉 需要 像 这 样 修改 构建 文件 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-data-jpa</artifactId> 
<exclusions> 
<exclusion> 
<artifactId>hibernate-entitymanager</artifactId> 
<groupId>org.hibernate</groupId> 
</exclusion> 
</exclusions> 
</dependency> 
<dependency> 
<groupId>org.eclipse.persistence</groupId> 
<artifactId>eclipselink</artifactId> 
<Vversion>2.5.2</version> 
</dependency> 





需要 注意 ， 根 据 你 所 选择 的 JPA 实 现 ， 这 里 可 能 还 需要 其 他 的 变 
更 。 你 可 以 参考 所 选择 的 JPA 实 现 文 档 以 了 解 更 多 细节 。 现 在 ， 我 们 重 
新 看 一 下 领域 对 象 ， 并 为 它们 添加 注解 ， 使 其 支持 JPA 持 久 化 。 

3.2.2 ”将 领域 对 象 标注 为 实体 


你 马上 将 会 看 到 ， 在 创建 repository 方 面 ，Spring Data 为 我 们 做 了 很 


多 非 第 棒 的 事情 。 但 是 ， 在 使 用 卫 A 了 映射 注解 标注 领域 对 象 方面 ， 它 却 
没有 提供 太 多 的 助 蔓 。 我 们 需要 打开 Ingredient、Taco 和 Order 关 ， 并 为 
其 添加 一 些 注解 ， 首 先是 Ingredient 类 ， 如 程序 清单 3.16 所 示 。 





程序 清单 3.16 ”为 ngredient 添 加 注解 使 其 支持 JPA 持 久 化 


package tacos; 


import Javax.perslstence.Entity ; 
import JjJavax.persistence.TId; 


Import lombok.AccessLevel,; 

import lombok.Data; 

Import lombok.NoArgsConstructor.; 
Import lombok.RequiredArgsConstructor; 


@Data 
QRequiredArgsConstructor 
@QNoArgsConstructor(access=AccessLevel .PRIVATE, force=true) 


@EnNtity 
public class Ingredient 1{ 


@Id 

private final String id; 
private final String name; 
private final Type type; 


public static enum Type 1{ 
WRAP, PROTEIN, VEGGIES, CHEESE, SAUCE 


} 





为 了 将 Ingredient 声 明 为 JPA 实 体 ， 它 必须 添加 @Entity 注 解 。 它 的 id 
属性 需要 使 用 @Id 注 解 ， 以 便于 将 其 指定 为 数据 库 中 唯一 标识 该 实体 的 
属性 。 


除了 JPA 特 定 有 的 注解 ， 你 可 能 会 友 现 我 们 在 类 级 列 湛 加 了 


@NoArgsConstructor 注 解 。JPA 需 nea i Lombok 
的 @NoArgsConstructor 注 解 能 够 帮助 我 们 实现 这 一 点 。 但 是 ， 我 们 不 想 
直接 使 用 它 ， 因 此 通过 将 access WO WE 
成 私有 的 。 因 为 这 里 有 必须 要 设置 的 final 必 性， 所 以 我 们 将 force 议 置 为 
true， 这 梓 Lombok 生 成 的 构造 颖 开会 将 它们 设置 为 null。 


我 们 还 添加 了 一 个 @RequiredArgsConstructor 注 解 。@Data 注 解 会 为 
我 们 添加 一 个 有 参 构 造 颖 ， 但 是 使 用 @NoArgsConstructor 注 解 之 后 ， 这 
个 构造 右 殉 会 极 移 除 反 。 现 在 ， 我 们 显 式 添加 
(@RequiredArgsConstructor 注 解 ， 以 确 你 除了 private 的 无 参 构造 器 之 外 ， 
我 们 还 会 有 一 个 有 参 构 造 莫 。 


接 下 来 ， 我 们 看 一 下 程序 清单 3.17 所 示 的 Taco 类 ， 看 看 它 是 如 何 标 
注 为 JPA 实 体 的 。 


程序 清单 3.17 ”将 Taco 标 注 为 实体 





package tacos; 

Import java.util.Date; 

Import java.util.List; 

import Javax.persistence.Entity; 

import JjJavax.persistence.GeneratedValue; 
Import javax.persistence.GenerationType; 
Import javax.persistence.TId; 

Import javax.persistence.ManyToMany; 
import Javax.persistence.OneToMany; 
import Javax.perslstence.PrePers1lst ; 
import JjJavax.validation.constraints.NotNull; 
import JjJavax.validation.constraints.Size; 


import lombok.Data; 


@Data 
@EnNntity 


public class Taco 1{ 


} 


@Id 
@QGeneratedValue(strategy=GenerationType.AUTO) 
private Long id; 


@QNotNull 
@Size(min=5, message="Name must be at least 5 characters long") 
private String name ; 


private Date createdAt ; 


@QManyToMany (targetEntity=Ingredient.class) 
@Size(min=1, message="You must choose at least 1 ingredient") 
private List<Ingredient> ingredients; 


@Prepersist 
void createdAt() { 
this.createdAt = new Date() ; 


} 


与 Ingredient 类 似 ，Taco 类 现在 添加 了 @Entity 注 解 ， 并 为 其 id 属性 


次 加 了 @Id 注 解 。 因 为 我 们 要 依赖 数据 库 日 动 生成 DD 值 ， 所 以 在 这 里 还 
为 id 属 性 设置 了 (@GeneratedValue， 将 它 的 strategy 设 置 为 AUTO。 


为 了 声明 Taco 与 其 关联 的 Ingredient 列 表 之 间 的 关系 ， 我 们 为 


ingredients 添 加 了 @BManyToMany 注 解 。 每 个 Taco 可 以 有 多 个 
Ingredient， 而 每 个 mgredient 可 以 是 多 个 Taco 的 组 成 部 分 。 


你 会 看 到 ， 在 这 里 有 一 个 新 的 方法 createdAt()， 并 使 用 了 


(@PrePersist 注 解 。 在 Taco 持 久 化 之 有 前， 我们 会 使 用 这 个 方法 将 createdAt 
设置 为 当前 的 日 期 和 时 间 。 了 最 后 ， 我 们 要 将 Order 对 象 标注 为 实体 。 程 
序 清单 3.18 展 示 了 新 的 Order 关 。 


程序 清单 3.18 ”将 Order 标 注 为 JPA 实 体 


package tacos; 


import 
import 
import 
import 


import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 


@Data 


@EnNntity 


Java. 
Java. 
Java. 
Java. 


]avax . 
]avax . 
]avax . 
]avax . 
]avax . 
]avax . 
]avax . 
]avax . 
]avax . 
]avax . 


10.Serializable; 
util.ArrayList; 
Util.Date,; 
Util.List; 


Entity; 
GeneratedValue; 
GenerationType; 
Id ; 

ManyToMany ; 
OneToMany ; 


persistence. 
persistence. 
persistence. 
persistence. 
persistence. 
persistence. 
persistence.PrePersist; 
persistence.Table,; 
validation.constraints.Digits,; 
validation.constraints.Pattern,; 


org.hibernate.validator.constraints.CreditCardNumber; 
org.hibernate.validator.constraints.NotBlank; 
lombok .Data; 


@Table(name="Taco Order") 
public class Order implements Serializable { 


private static final long serialVersionUID = 


@Id 


1L ; 


@QGeneratedValue(strategy=GenerationType.AUTO) 
private Long id; 


private Date placedAt; 


@QManyToMany (targetEntity=Taco.class) 


private List<Taco> tacos = 


new ArrayList<>(); 


public void addDesign(Taco design) { 
this.tacos.add(design); 


} 


Q@PrePersist 


void placedAt() { 


this.placedAt = 


} 


new Date( ) ; 


| 


我 们 可 以 看 到 ，Order 所 需 的 变更 惑 是 Taco 的 翻版 。 但 是 ， 在 类 级 
别 这 里 有 了 一 个 新 的 注解 ， 即 @Table。 它 表明 Order 实 体 应 该 持久 化 到 
数据 库 中 名 为 Taco_Order 的 表 中 。 


我 们 可 以 将 这 个 注解 用 到 所 有 的 实体 上 ， 但 是 只 有 Order 有 必要 
样 做 。 如 果 没 有 它 ，JPA 默 认 会 将 实体 持久 化 到 名 为 Order 的 表 中 ， 但 是 
order 是 SQL 的 保留 字 ， 这 样 做 的 话 会 产生 问题 。 实 体 都 已 经 标注 好 了 ， 
现在 我 们 该 编 与 repository 了。 


3.2.3 ”声明 JPA repository 


在 JDBC 版 本 的 repository 中 ， 我 们 显 陈 下 明 想 要 repository 提 供 的 方 
法 。 但 是 ， 信 助 Spring Data， 我 们 可 以 扩展 CrudRepository 接 口 。 举 例 
来 说 ， 如 下 是 新 的 IngredientRepository 接 口 。 


package tacos.data; 
Import org.springframework.data.repository.CrudRepository ; 


Import tacos.Ingredient,; 


public Interface IngredientRepository 
extends CrudRepository<Ingredient, String> 1{ 





CrudRepository 定 义 了 很 多 用 于 CRUD 〔〈 创 建 、 谈 取 、 更 新 、 删 除 ) 
操作 的 方法 。 注 是 ， 它 是 参数 化 的 ， 第 一 个 参数 是 repository 要 持久 化 的 


实体 类 型 ， 第 二 个 参数 是 实体 ID 属 性 的 类 型 。 对 于 IngredientRepository 
来 说 ， 参 数 应 该 是 Ingredient 和 String。 


我 们 可 以 非常 简单 地 定义 TacoRepository: 


package tacos.data; 


import org.springframework.data.repository.CrudRepository; 


import tacos.Taco; 


public interface TacoRepository 
extends CrudRepository<Taco, Long> { 





IngredientRepository 和 TacoRepository 之 间 唯 一 比较 明显 的 区 别 束 是 
CrudRepository 的 参数 。 在 这 里 ， 我 们 将 其 设置 为 Taco 和 Long， 从 而 指 
定 Taco 实 体 〈 及 其 ID 类 型 ) 是 该 repository 接 口 的 持久 化 单元 。 最 后 ， 相 
同 的 变更 可 以 用 到 OrderRepository 上 : 


package tacos.data; 
Import org.springframework.data.repository.CrudRepository,; 


Import tacos.Order; 


public interface OrderRepository 
extends CrudRepository<Order, Long> { 





现在 ， 我 们 有 了 3 个 repository。 你 可 能 会 想 ， 我 们 应 该 需要 编写 它 
们 的 实现 类 ， 包 括 每 个 实现 类 所 需 的 十 多 个 方法 。 但 是 ，Spring Data 
JPA 市 来 的 好 消息 是 ， 我 们 根本 吏 不 用 编写 实现 类 ! 当 应 用 局 动 的 时 


候 ，Spring Data JPA 会 在 运行 期 日 动 生成 实现 类 。 这 意味 看 ， 我 们 现在 
束 可 以 使 用 这 些 repository 了 。 我 们 只 需要 像 使 用 基于 JDBC 的 实现 那样 
将 它们 注入 控制 右 中 束 可 以 了 。 


CrudRepository 所 提供 的 方法 对 于 实体 的 通用 持久 化 是 非常 有 用 
的 。 但 是 ， 如 采 我 们 的 需求 并 不 局 限于 基本 持久 化 ， 那 又 该 怎么 办 呢 ? 
接 下 来 ， 我 们 看 一 下 如 何 自 定 义 repository 来 执行 特定 领域 的 查询 。 


3.2.4 目 定 义 JPA repository 


假设 除了 CrudRepository 提 供 的 基本 CRUD 操 作 之 外 ， 我 们 还 需要 获 
取 投 弟 到 指定 邮编 (Zip〉 的 订单 。 实 际 上 ， 我 们 只 需要 添加 如 下 的 方 
法 声明 到 OrderRepository 中 ， 这 个 问题 就 解决 了 了: 


List<Order> findByDeliveryZip(String deliveryZip); 


当 创 建 repository 实 现 的 时 候 ，Spring Data 会 检查 repository 接 口 的 所 
有 方法 ， 解 析 方 法 的 名 称 ， 并 基于 被 持久 化 的 对 象 来 试图 推测 方法 的 目 
的 。 本 质 上 ，Spring Data 定 义 了 一 组 小 型 的 领域 特定 语言 (Domain- 
Specific Language，DSL) ， 在 这 里 持久 化 的 细 攻 都 是 通过 repository 方 
法 的 签名 来 描述 的 。 


Spring Data 能 够 知道 这 个 方法 是 要 奏 找 Order 的 ， 因 为 我 们 使 用 
Order 对 CrudRepository 进 行 了 参数 化 。 方 法 名 findByDeliveryZipO 确 定 访 
方法 需要 根据 deliveryZ 让 属性 相 匹 配 来 得 找 Order， 而 deliveryZip 的 值 是 
作为 参数 传递 到 方法 中 来 的 。 


findByDeliveryZip 0 方法 非常 徐 单 ， 但 是 Spring Data 也 能 处 理 更 加 
有 意思 的 方法 名 称 。repository 方 法 是 由 一 个 动词 、 一 个 可 选 的 主题 
(Subject) 、 关 键 词 By 以 及 一 个 断言 所 组 成 的 。 在 findByDeliveryZip() 
这 个 样 例 中 ， 动 词 是 fnd， 断 言 是 DeliveryZip， 主 题 并 没有 指定 ， 上 暗合 


的 主题 是 Order。 


我 们 考虑 另外 一 个 更 复杂 的 样 例 。 假 设 我 们 想 要 查找 投递 到 指定 邮 
编 且 在 一 定时 间 苑 围 内 的 订单 。 在 这 种 情况 下 ， 我 们 可 以 将 如 下 的 方法 
洪 加 a 到 OrderRepository 中 ， 它 束 能 达到 我 们 的 目的 。 


string deliveryZip，Date startDate, Date endDate); 

图 3.2 展现 了 Spring Data 在 生成 repository 实 现 的 时 候 是 如 何 解析 和 
理解 readOrdersByDeliveryZipAndPlacedAtBetween0 方 法 的 。 我 们 可 以 看 
到 ， 在 readOrdersByDeliveryZipAndPlacedAtBetween() 中 ， 动 词 是 read。 
Spring Data 会 将 get、read 和 find 视 为 同义词 ， 它 们 都 是 用 来 获取 一 个 或 
多 个 实体 的 。 男 外 ， 我 们 还 可 以 使 用 count 作 为 动词 ， 它 会 返回 一 个 int 
值 ， 代 表 匹 配 实体 的 数量 。 


各 声 日 

这 个 方法 将 会 读 取 数 据 。 开 * 斑 内 妥 允 配 的 属性 

(这 里 也 允许 使 用 “get” 

或 find”) 值 必 须要 在 给 定 的 范围 内 
.And... 


readOrdersByDeliveryZipAndPlacedAtBetween() 


死 配 “ .deliveryZip” 匹配 “.placedAt” 或 
或 “.delivery.zip" 属 性 “.placed.at”* 属 性 





图 3.2 ”Spring Data 解 析 repository 方 法 签名 来 确定 要 执行 的 查询 


尽管 方法 的 主题 是 可 选 的 ， 但 是 这 里 要 俘 找 的 束 是 Order。Spring 
Data 会 急 略 主题 中 大 部 分 的 单词 ， 所 以 你 尽 可 以 将 方法 命名 为 
readPuppiesBy.…， 它 依然 会 去 得 找 Order 实 体 ， 因 为 CrudRepository 的 其 
型 羡 参 数 化 的 。 


单词 By 后 面 的 断言 是 方法 签名 中 了 最 为 有 意思 的 一 部 分 。 在 本 例 中 ， 
盯 言 指定 了 Order 的 两 个 属性 ;deliveryZip 和 placedAt。deliveryZip 属 性 
的 值 必须 要 等 于 方法 第 一 个 参数 传 入 的 值 。 关 键 字 Between 表 明 placedAt 
属性 的 值 必须 要 位 于 方法 最 后 两 个 参数 的 值 之 间 。 


除了 Eguals 和 Between 操 作 之 外 ，Spring Data 方 法 签名 还 能 包括 如 下 
的 操作 符 : 


e IsAfter、 After、IsGreaterThan、GreaterThan 
e。 [SGreaterIhanEqual、 GreaterIhanEqual 

e IsBefore、Before、IsLessThan、LessThan 
。 IsLessThanEqual、LessThanEqual 

e IsBetween、 Between 

e IsNull、Null 

e IsNotNull、 NotNull 

e IsIn、In 

e LSNotin、Notin 

e IsStartingWith、 StartingWith、 StartsWith 
e。 IsEndingWith、 EndingWith、EndsWith 

e IsContaining、Contaning、(Contains 

e IsLike、 Like 

e IsNotLike、 NotLike 


e Islrue、 True 
e IsFalse、False 
e Is、Equals 

e IsNot、 Not 


e IgnoringCase、1gnoresCase 
作为 IgnoringCase/IgnoresCase 的 答 代 方案 ， 我 们 还 可 以 在 方法 上 添 


加 AllIgnoringCase 或 AllIgnoresCase， 这 样 它 驶 会 忽略 所 有 String 对 比 的 
大 小 写 。 例 如 ， 请 看 如 下 方法 : 


List<Order> findByDeliveryToAndDeliveryCityA1L1IgnoresCase( 
String deliveryTo, String deliveryCity ) ; 
最 后 ， 我 们 还 可 以 在 方法 名 称 的 结尾 处 添加 OrderBy， 实 现 结 采 集 
根据 有 霖 个 列 排序 。 例 如 ， 我 们 可 以 按照 deliveryTo 属 性 排序 : 


List<Order> findByDeliveryCityOrderByDeliveryTo(String city ) ; 


尽 官 方法 名 称 约 定 对 于 相对 简单 的 查询 非常 有 用 ， 但 是 ， 不 难 想 
月 ， 对 于 更 为 复 洒 的 查询 ， 方 法 名 可 能 会 面临 失控 的 风险 。 在 这 种 情况 
下 ， 可 以 将 方法 定义 为 任何 你 想 要 的 名 称 ， 并 为 其 评 加 @Query 注 解 ， 
从 而 明确 指明 方法 调用 时 要 执行 的 查询 ， 如 下 面 的 样 例 所 示 : 


QQuery("0rder o where o.deliveryCity='Seattle'") 


List<Order> readOrdersDeliveredInSeattle( ) ; 





在 本 例 中 ， 通 过 使 用 @Query， 我 们 声明 只 奏 询 所 有 投递 到 Seattle 的 
订 蛙 。 但 是 ， 我 们 可 以 使 用 @Query 执 行 任 何 想 要 的 查询 ， 有 些 查 询 是 
通过 方法 命名 约定 很 难 甚至 根本 无 法 实现 的 。 


3.3 ”小 结 


。 SpringHJdbcTemplate 能 够 极 大 地 简化 JDBC 的 使 用 。 

。 在 我 们 需要 知道 数据 库 所 生成 的 ID 信 时 ， 可 以 组 合 使 用 
PreparedStatementCreator 和 KeyHolder。 

。 为 了 催化 数据 的 插入 ， 可 以 使 用 SimpleJdbcInsert。 

。 Spring Data JPA 能 够 极 大 地 人 徐 化 JPA 持 和 久 化 ， 我 们 只 需 编写 
repository 接 口 即 可 。 





[1] 我 要 承认 这 里 对 ObjectMapper 的 使 用 并 不 高 明 ， 但 是 我 们 毕竟 己 经 
将 Jackson 引 入 到 了 类 路 径 中 ， 这 和 古 由 Spring Boot 的 web starter 引 入 的 。 
另外 ， 使 用 ObjectMapper 将 对 象 映射 为 Map 要 比 复制 对 象 的 每 个 属性 到 
Map 中 容易 得 多 。 你 尽 可 以 使 用 其 他 技术 来 构建 Inserter 对 象 所 需 的 
Map， 以 替换 对 ObjectMapper 的 使 用 。 


第 4 章 ” 体 护 Spring 


自动 配置 Spring Security 


设置 目 定义 的 用 户 存 储 


目 定义 登录 


防范 CSRF 攻 击 


知道 用 户 是 谁 





有 一 点 不 知道 你 是 售 在 意 过 ， 那 殉 是 在 电视 剧 中 大 多 数 人 从 不 锁 
| ] 。 在 Leave it to Beaver 热 播 的 时 代 ， 人 们 不 锁 门 这 事 并 不 全 得 大 人 恢 小 
怪 ， 但 是 在 这 个 隐私 和 安全 被 看 得 极其 重要 的 年 代 ， 看 到 电视 剧 中 的 角 
色 允 许 别 人 大 播 大 探 地 进入 目 己 的 元 所 或 家 中 实在 让 人 难以 置信 。 


现在 ,信息 可 能 是 我 们 最 有 价值 的 东西 ,一些 不 怀 好 音 的 人 想 尽 办 
法 试图 偷偷 进入 不 安全 的 应 用 程序 来 伪 取 我 们 的 数据 和 身份 信息 。 作 为 


软件 开 肥 人 员 ， 我 们 必须 采取 措施 来 保护 应 用 程序 中 的 信息 。 无 论 你 是 
通过 用 户 名 /密码 来 你 护 电 子 邮件 账号 ， 还 是 基于 交易 PIN 来 傈 护 经 纪 账 
户 ， 安 全 性 都 是 绝 大 多 数 应 用 系统 中 的 一 个 重要 切面 。 


4.1 司 用 Spring Security 


保护 Spring 应 用 的 第 一 步 就 是 将 Spring Boot security starter 依 赖 深 加 
到 构建 文件 中 。 在 项 目的 pom.xml 文 件 中 ， 湛 加 如 下 的 <dependency> 条 
日 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-security</artifactId> 
</dependency> 





如 果 你 使 用 Spring Tool Suite， 那 么 这 个 过 程 会 更 加 简单。 用 女 标 石 
键 点 击 pom.xml 文 件 并 在 Spring 弹出 菜单 中 选择 “Edit Starters”， 将 会 出 
现 “Edit Spring Boot Starters” 对 话 框 ， 在 “Core” 分 类 中 选择 “Security” 条 
目 ， 如 图 4.1 所 示 。 


Edit Spring Boot Starters 


Service URL http://start. spring.io ~| 
Frequently Used 
Actuator Cassandra DevTools 
Groovy Templates H2 JDBC 
JPA Lombok Rest Repositories 
Security Thymeleaf Web 
Available: Selected: 
security @) x security 
X DevTiools 
v Cloud Core X Lombok 
X Actuator 
Cloud Security x JPA 
Cloud OAuth2 XxX Hz 
X Thymeleaf 
v Core X Web 
Security 
Make Default Clear Selection 


图 4.1 使 用 Spring Tool Suite 玖 加 security starter 


不 官 你 是 否 相 信 ， 要 保护 我 们 的 应 用 ， 只 和 需 洪 加 这 项 依赖 束 可 以 
了 。 当 应 用 局 动 的 时 候 ， 目 动 配置 功能 会 ea Security 出 现在 
了 类 路 入 中 ， 因 此 它 会 初始 化 一 些 基 本 的 安全 配置 。 


如 末 你 想 试 一 下 ， 可 以 司 动 应 用 并 尝试 访问 主页 〈 或 者 任意 页 
面 )。 ni 弹出 一 个 HTTP basic 认 证 对 话 框 并 提示 你 进行 认证 。 要 
想 通 过 这 个 认证 ， 你 需要 一 个 用 户 名 和 和 窒 码 。 用 户 名 为 user， 而 密码 则 

ly 它 会 被 写 入 应 用 的 日 总 文件 中 。 日 志和 条目 大 致 如 下 所 


人 小 : 


假设 输入 了 正确 的 用 户 名 和 和 密码， 你 就 有 权限 访问 应 用 了 。 


看 上 去 体 护 Spring 应 用 是 一 项 非常 简单 的 任务 。 现 在 ，Taco Cloud 
应 用 已 经 安全 了 ， 我 们 可 以 结束 本 下 并 进入 下 一 个 话题 了 。 但 是 ， 在 继 
续 下 一 步 之 前 ， 我 们 回顾 一 下 上 自动 配置 提供 了 什么 类 型 的 安全 性 。 


通过 将 security starter 添 加 到 项 目的 构建 文件 中 ， 我 们 得 到 了 如 下 的 
安全 特性 : 


。 所 有 的 HITP 请 求 路 径 都 需要 认证 ; 

。 不 需要 特定 的 角色 和 权限 ; 

。 没有 登录 页 面 ; 

。 认证 过 程 是 通过 HTTP basic 认 证 对 话 框 实现 的 ; 
。 系统 只 有 一 个 有 用户， 用户 名 为 user。 


这 是 一 个 很 好 的 开端 ， 但 是 我 相信 大 多 数 应 用 (包括 Taco Cloud) 
的 安全 需求 与 这 些 基 础 的 安全 特性 截然 不 同 。 


如 果 想 要 确保 Taco Cloud 应 用 的 安全 性 ， 我 们 还 有 很 多 的 工作 要 
做 。 我 们 至 少 要 配置 Spring Security 实 现 如 下 功能 : 


。 通过 登录 页 面 来 提示 用 户 进 行 认证 ， 而 不 是 使 用 HTTP basic 对 话 
框 ; 

。 提供 多 个 用 户 ， 并 提供 一 个 注册 页 面 ， 这 样 Taco Cloud 的 新 用 户 能 
够 注册 进来 ; 


。 对 不 同 的 请 求 路 径 ， 执 行 不 同 的 安全 规则 。 举 例 来 说 ， 主 页 和 注册 
页 面 根本 不 需要 进行 认证 。 
为 了 满足 Taco Cloud 的 安全 需求 ， 我 们 需要 编写 一 些 好 式 的 配置 ， 
禾 羡 反目 动 配 置 为 我 们 提供 的 功能 。 我 们 首先 配置 一 个 合适 的 用 户 存 
储 ， 这 样 承 能 有 多 个 用 户 了 。 


4.2 配置 Spring Security 


多 年 以 来 ， 出 现 了 多 种 配置 Spring Security 的 方式 ， 包 括 见 长 的 基 
于 XML 的 配置 。 圣 运 的 是 ， 了 最 近 几 个 厂 本 的 Spring Security 都 文 持 基于 
Java 有 的 配置 ， 这 种 方式 更 加 易于 网 读 和 编 与 。 


在 本 章 结束 之 前 ， 我 们 会 使 用 基于 Java 的 Spring Security 配 置 完成 
Taco Cloud 安 全 性 需要 的 所 有 设置 。 人 但是， 首先 ， 我 们 需要 编写 程序 清 
单 4.1 中 这 个 基础 的 配置 类 。 


程序 清单 4.1 Spring Security 的 基础 配置 类 


package tacos.security; 


import org.springframework.context.annotation.Bean,; 

Import org.springframework.context.annotation.Configuration; 

import org.springframework.security.config.annotation.web 
.ConNnfiguration.EnableWebSecurity; 

import org.springframework.security.config.annotation.web 


.ConNnfiguration.WebSecurityConfigurerAdapter; 
@Configuration 


@EnableWebSecurity 
public class SecurityConfig extends WebSecurityConfigurerAdapter 1{ 


} 





这 个 基础 的 安全 配置 都 为 我 们 做 了 些 什么 呢 ? dd 但 是 
它 确 实 朝 着 我 们 所 需 的 安全 性 需求 同 前 推进 了 一 步 。 如 采 此 时 你 再 次 访 
问 Taco Cloud 主 页 ， 那 么 pa 但 是 ， 现 在 不 再 
是 提示 HTTP basic 认 证 的 对 话 框 ， 而 是 会 展现 如 图 4.2 所 示 的 登录 表单 。 


O08@ « localhost , ) JU 


Login with Username and Password 


Passwo rd: 








图 4.2 ”Spring Security 为 我 们 免费 提供 的 简单 登录 页 


提示 : 在 进行 手动 安全 测试 的 时 候 ， 你 会 有 友 现 将 浏 抠 硕 设 置 
为 私有 或 隐 喘 模式 会 非常 有 用 。 这 能 够 确保 每 次 打开 一 个 私有 / 
手 吴 窗口 都 会 有 一 个 新 的 会 话 。 每 次 你 都 需要 重新 登录 应 用 ， 但 


是 你 尽 可 以 放心 ， 在 安全 性 方面 做 得 所 有 变 喝 都 会 生效 ， 旧 会 话 
不 会 有 任何 残留 ， 芒 但 我 们 看 到 变更 的 效 朱 。 





是 一 个 很 小 的 改进 ， 通 过 Web 页 面 提示 登录 (尽管 看 上 去 非常 简 
陋 〉 要 比 HTTP basic 对 话 框 更 友好 一 些 。 在 4.3.2 小 节 ， 我 们 将 会 自 定义 
登录 页 面 。 不 过 ， 我 们 现在 的 任务 是 配置 用 户 存 储 ， 使 系统 能 够 处 理 多 
个 用 户 。 


事实 上 ，Spring Security 为 配置 用 户 存 储 提 供 了 多 个 可 选 方案 ， 包 
括 : 


。 基于 内 存 的 用 户 存 储 ; 
。 其 于 JDBC 的 用 户 存 储 ; 
。 以 LDAP 作 为 后 端的 用 户 存 储 ; 
目 定 义 用 户 详情 服务 。 


不 官 使 用 哪 种 用 户 存 储 ， 你 都 可 以 通过 窗 曾 
WebSecurityConfigurerAdapter 基 础 配置 关中 定义 的 configure0) 方 法 来 进 
行 配置 。 背 和 完 ， 我 们 可 以 将 如 下 的 方法 添加 a 到 SecurityConfig 类 中 : 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 


throws Exception { 





现在 ， 我 们 需要 使 用 指定 的 AuthenticationManagerBuilder 符 换 上 面 
的 省 略 写 ， 以 此 来 定义 在 认证 过 程 中 如 何 伍 找 用 户 。 我 们 先 来 看 一 下 基 
于 内 存 的 用 户 存 储 。 


4.2.1 基于 和 内存 的 用 户 存 储 


用 户 信息 可 以 存 储 在 内 存 之 中 。 假 设 我 们 只 有 数量 有 限 的 几 个 用 
户 ， 而 且 这 些 用 户 几 乎 不 会 友 生 变化 ， 在 这 种 情况 下 ， 将 这 些 用 户 和 定义 
成 安全 配置 的 一 部 分 是 非常 简单 的 。 


例如 ， 程 序 清单 4.2 展 示 了 如 何在 内 存 用 户 存 储 中 配置 两 个 用 户 ， 
BR] “buzz” 和 “woody”。 


程序 清单 4.2 ”在 内 存 用 户 存 储 中 定义 用 户 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 
auth 
.inMemoryAuthentication() 
.WithUser("buzz") 
.password("infinity") 


.authorities("ROLE USER") 
.and() 
.withUser("woody") 
.password("bullseye") 
.authorities("ROLE USER"); 





我 们 可 以 看 到 ，AuthenticationManagerBuilder 使 用 构造 者 
(builder) 风格 的 接口 来 构建 认证 细节 。 在 本 例 中 ， 我 们 在 安全 配置 中 
调用 ip MemoryAuthentication(0) 方 法 来 指定 用 户 信 息 。 


每 次 调用 withUser0O 都 会 配置 一 个 用 户 ， 这 个 方法 给 定 的 值 是 用 户 
名 ， 而 密码 和 授权 信息 是 明 过 password() 和 authorities() 方 法 来 指定 的 。 
如 程序 清单 4.2 中 所 示 ， 两 个 用 户 都 授予 了 ROLE_USER 权 限 。 用 户 buzz 
时 密码 为 “infinity”， 而 Woody 的 密友 为 “bullseye”。 


对 于 测试 和 简单 的 应 用 来 讲 ， 基 于 内 存 的 用 尸 存 储 是 很 有 用 的 ， 但 
是 这 种 方式 不 能 很 方便 地 编辑 用 户 。 如 果 需 要 新 增 、 移 除 或 变更 用 户 ， 
那么 你 要 对 代码 做 出 必要 的 修改 ， 然 后 重新 构建 和 部 闭 应 用 。 


对 于 Taco Cloud 应 用 来 说 ， 我 们 希望 顾客 能 够 在 应 用 中 进行 注册 ， 
并 且 能 够 管理 目 己 的 用 户 账 志 。 这 明显 与 内 存 用 户 存储 的 限制 不 符 ， 所 
以 我 们 接 下 来 看 一 下 另外 一 种 方式 ， 这 种 方式 允许 使 用 数据 库 后 闹 作 为 
用 户 存 储 。 


4.2.2 ”基于 JDBC 的 用 户 存 储 


用 户 信 息 通 篆 会 在 关系 型 数据 库 中 进行 维护 ， 基 于 JDBC 的 用 户 存 
储 方案 会 更 加 合理 一 些 。 程 序 清 单 4.3 展 示 了 使 用 JDBC 对 存储 在 关系 型 
数据 库 中 的 用 户 信 息 进 行 认 证 所 需 的 Spring Security 配 置 。 
程序 清单 4.3 ”基于 JDBC 用 户 存 储 进行 认证 


QAutowired 
DataSource dataSource ; 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 


throws Exception { 


auth 
.jdbcAuthentication() 
.dataSource(dataSource); 





在 这 里 的 configure0 实 现 中 ， 调 用 了 了 AuthenticationManagerBuilder 的 
jdbcAuthentication() 方 法 。 我 们 必须 还 要 设置 一 个 DataSource， 这 样 它 才 


能 知道 如 何 访问 数据 库 。 这 里 的 DataSource 是 通过 上 自动 装配 的 技巧 获取 
到 的 。 


重 与 默认 的 用 户 坦 询 功 能 


ea 置 能 够 让 一 切 运转 起 来 ， 但 是 它 对 我 们 的 数据 库 模 式 有 
一 些 要 求 ， 预 期 示 些 存储 用 户 数据 的 表 已 经 存在 。 更 具体 来 说 ， 下 面 的 
ee Security 内 部 ， 并 展现 了 当 奉 找 用 户 信 息 时 所 执 

行 的 SQL 查询 语句 : 


public static final String DEF USERS BY USERNAME QUERY = 
"select username,password,enabled ”+ 
"from users " + 
"where username = ? ; 

public static final String DEF AUTHORITIES BY USERNAME QUERY = 
"select username,authority " + 
"from authorities ”十 


"where username = 2»"，; 

public static final String DEF GROUP AUTHORITIES BY USERNAME QUERY = 
"select g.id, g.group name, ga.authority " + 
"from groups g, group members gm, group authorities ga " + 
"where gm.username = ? "+ 
"and g.id = ga.group id " + 
"and g.id = gm.group id"; 





在 第 一 个 查询 中 ， 我 们 获取 了 用 户 的 用 户 名 、 密 码 以 及 是 个 司 用 的 
信息 ， 用 来 进行 用 户 认 证 。 接 下 来 的 查询 查找 了 用 户 所 授予 的 权限 ， 用 
来 进行 你 权 。 在 最 后 一 个 查询 中 ， 奏 找 了 用 户 作为 群 组 的 成 员 所 授予 的 
权限 。 


如 末 你 能 够 在 数据 库 中 定义 和 项 充满 足 这 些 碍 询 的 表 ， 那 么 基本 上 
束 不 二 要 由 做 什么 额外 的 事情 了。 但 是 ， 也 有 可 能 你 的 数据 库 与 上 述 有 的 


不 一 致 ， 那 么 你 会 硕 副 在 查询 上 有 蝎 多 的 控制 权 。 如 采 古 这 梓 ， 那 么 我 
们 可 以 按照 程序 请 单 4.4 所 示 的 方式 配置 目 己 的 查询 : 
程序 清单 44 自 定义 用 户 详情 查询 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 


auth 
.jdbcAuthentication() 
.dataSource(dataSource) 


.USersByUsernameQuery( 
"select username, password, enabled from Users ”十 
"where username=?") 

.authoritiesByUsernameQuery( 
"select username, authority from UserAuthorities " + 
"where username=?"); 





在 本 例 中 ， 我 们 只 重 写 了 认证 和 基本 权限 的 得 询 语句 ， 但 是 通过 调 
用 groupAuthorities ByUsername0 方 法 ， 我 们 也 能 够 将 群 组 权限 重 写 为 目 
定义 的 但 询 语 句 。 


循 得 询 的 基本 协议 。 所 有 和 奏 询 都 将 用 户 名 作为 唯一 的 参数 。 认 证 得 询 会 
选取 用 户 名 、 密 人 码 以 及 局 用 状态 信息 。 权 限 查 询 会 选取 零 行 或 多 行 包含 
该 用 户 名 及 其 权限 信息 的 数据 。 群 组 权限 查询 会 选取 和 零 行 或 多 行 数据 ， 
每 行 数据 中 都 会 包含 群 组 ID、 群 组 名 称 以 及 权限 。 


将 罗 认 的 SQL 碍 询 答 换 为 目 定 义 的 设计 时 ， 很 重要 的 一 点 融 是 要 放 
台 


使 用 园 码 后 的 黎 但 


看 一 下 上 面 的 认证 查询 ， 它 预期 用 户 密码 存储 在 了 数据 库 之 中 。 这 
里 唯一 的 问题 在 于 如 果 密 码 明文 存储 ， 就 很 容易 受到 黑客 的 窃取 。 但 
是 ， 如 果 数 据 库 中 的 密码 进行 了 转 码 ， 那 么 认证 就 会 失败 ， 因 为 它 与 用 
户 提交 的 明文 密码 并 不 匹配 。 


为 了 解决 这 个 问题 ， 我 们 需要 借助 passwordEncoder() 方 法 指定 一 个 
密 但 转 码 器 (encoder) : 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 


auth 
.jdbcAuthentication() 
.dataSource(dataSource) 
.USersByUsernameQuery( 


"select username, password, enabled from Users ”十 
"Where username=?") 

.authoritiesByUsernameQuery( 
"select username, authority from UserAuthorities " + 
"Where username=?") 

.passwordEncoder(new StandardPasswordEncoder("53cr3t"); 





passwordEncoder() 方 法 可 以 接受 Spring Security 中 PasswordEncoder 接 
口 的 任意 实现 。Spring Security 的 加 和 密 模 块 包括 了 多 个 这 样 的 实现 。 


e。 BCryptPasswordEncoder: 使 用 bcrypt 强 哈 希 加 密 。 

e。 NoOpPasswordEncoder: 不 进行 任何 转 码 。 
Pbkdf2PasswordEncoder: 使 用 PBKDF2 加 密 。 
SCryptPasswordEncoder: 使 用 scrypt 哈 希 加 密 。 
StandardPasswordEncoder: 使 用 SHA-256 哈 硕 加 答 。 


上 述 的 代码 中 使 用 了 StandardPasswordEncoder， 但 是 你 可 以 使 用 任 
意 一 个 实现 ， 如 有 果 内 置 的 实现 无 法 满足 需求 时 ， 你 甚至 可 以 提供 目 定 义 


YI AAA 、 


的 实现 。PasswordEncoder 接 口 非 党 简单: 


public interface PasswordEncoder { 
String encode(CharSequence rawPassword); 


boolean matches(CharSequence rawPassword, String encodedPassword ) ; 


} 





不 管 你 使 用 哪 一 个 密码 转 码 磺 ， 者 需要 理解 一 点 ， 即 数据 库 中 的 冤 
码 是 永远 不 会 解码 的 。 用 户 在 登录 时 所 采取 的 案 略 与 之 相反 ， 输 入 的 答 
人 码 会 控 照 相同 的 算法 进行 转 人 码 ， 然 后 与 数据 库 中 已经 转 人 码 过 的 和 窜 码 进行 
对 比 。 这 个 对 比 是 在 PasswordEncoder 的 matches0) 方 法 中 进行 的 。 


最 终 ， 我 们 实现 了 在 数据 库 中 维护 Taco Cloud 用 户 数据 。 但 是 ， 我 
并 没有 采用 jdbcAuthentication0， 因 为 我 想到 了 画 外 一 种 认证 方案 。 在 
介绍 访 方 案 之 前， 我 们 先 看 一 下 如 何 配置 Spring Security 依 赖 另 一 种 通 
用 的 用 户 数 据 产 : 使 用 LDAP (Lightweight Directory Access Protocol， 
轻 量 级 目录 访问 协议 ) 访问 的 用 户 存 储 。 


4.2.3 ”以 LDAP 作 为 后 问 的 用 尸 存 储 


为 了 配置 Spring Security 使 用 基于 LDAP 认证 ， 我 们 可 以 使 用 
ldapAuthentication() 方 法 。 这 个 方法 在 功能 上 类 似 于 
jdbcAuthentication()， 只 不 过 是 LDAP 版 本 。 如 下 的 configure() 方 法 展现 
了 LDAP 认 证 的 简单 配置 : 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 
auth 


.ldapAuthentication() 
.UsSerSearchFilter("(uid={6})") 
.groupSearchFilter("member={06}"); 





方法 userSearchFilter() 和 groupSearchFilter() 用 来 为 基础 LDAP 查 询 提 
供 过 滤 条 件 ， 写 们 分 别 用 于 搜索 用 户 和 组 。 默 认 情 况 下 ， 对 于 用 户 和 组 
的 基础 查询 都 是 空 的 ， 也 就 是 表明 搜索 会 在 LDAP 层 级 结构 的 根 开 始 。 
但 是 我 们 可 以 通过 指定 查询 基础 来 改变 这 个 默认 行为 : 

QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 


auth 
.ldapAuthentication() 


.UsSerSearchBase("ou=people") 
.UsSerSearchFilter("(uid={6})") 
.groupSearchBase("ou=groups") 
.groupSearchFilter("member={06}"); 





userSearchBase() 方 法 为 得 找 用 户 提供 了 基础 租 询 。 同 样 的 ， 
groupSearchBase(O) 为 得 找 组 指定 了 基础 租 询 。 我 们 声明 用 户 应 访 在 名 为 
people 的 组 织 单元 下 搜索 而 不 是 从 根 开 始 ， 而 组 应 该 在 名 为 groups 的 组 
织 单元 下 搜索 。 


配置 密码 比 对 


基于 LDAP 认 证 的 默认 案 略 是 进行 绑 定 操作 ， 下 接 通 过 LDAP 服 务 
器 认证 用 户 。 另 一 种 可 选 的 方式 是 进行 比 对 操作 。 这 涉及 将 输入 的 密码 


及 达到 LDAP 目 录 上 ， 并 要 求 服务 需 将 这 个 密码 和 用 户 的 密 但 进行 比 
对 。 因 为 比 对 十 在 LDAP 服 务 占 内 完成 的 ， 实 际 的 密码 能 体 持 私密 。 


如 采 你 布 望 通过 密 但 比 对 进行 认证 ， 可 以 通过 声明 
passwordCompare() 方 法 来 实现 : 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 
auth 


.ldapAuthentication() 


.USerSearchBase("ou=people") 
.UserSearchFilter("(uid={6})") 
.groupSearchBase("ou=groups") 
.groupSearchFilter("member={06}") 
.passwordCompare( ); 





团 认 情况 下 ， 在 登录 表单 中 提供 的 密码 将 会 与 用 户 的 LDAP 条 目 中 
的 userPassword 属 性 进行 比 对 。 如 有 果 和 密码 们 保存 在 不 同 的 属性 中 ， 可 以 
通过 passwordAttribute() 方 法 来 声明 密码 属性 的 名 称 : 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 
auth 
.ldapAuthentication() 
.USerSearchBase("ou=people") 


.USerSearchFilter("(uid={06})") 
.groupSearchBase("ou=groups") 
.groupSearchFilter("member={06}") 
.passwordCompare() 

.passwordEncoder(new BCryptPasswordEncoder()) 
.passwordAttribute("passcode"); 





在 本 例 中 ， 我 们 指定 了 要 与 给 定 密码 进行 比 对 的 是 “passcode” 属 


性 。 男 外 ， 我 们 还 可 以 指定 密码 转 码 疾 。 在 进行 服务 器 并 密码 比 对 时 ， 

有 一 点 非 党 好 ， 那 束 古 实际 的 密码 在 服务 器 问 是 私密 的 。 但 是 进行 笑 试 
的 密码 还 是 需要 通过 线路 传输 到 LDAP 服 务 器 上 ， 这 可 能 会 被 黑客 所 拦 
币 。 为 了 避免 这 一 点 ， 我 们 可 以 通过 调用 passwordEncoder0) 方 法 指定 加 


EH 


在 表面 的 例子 中 ， 和 密码 使 用 bcrypt 密 人 码 哈 希 疯 数 加 窗 。 这 和 需要 LDAP 
服务 左上 的 密码 也 使 用 bcrypt 进 行 了 加 答 。 


引用 远程 的 LDAP 服 务 器 


到 目前 为 止 ， 我 们 忽略 的 一 件 事 束 是 CDAP 和 实际 的 数据 在 哪里 。 
我 们 很 开心 地 配置 Spring 使 用 LDAP 服 务 絮 进行 认证 ， 但 是 服务 占 在 哪 
里 呢 ? 

于 认 情 况 下 ，Spring Security 的 LDAP 认 证 假设 LDAP 服 务 右 监听 本 


机 的 33389 端 口 。 但 是 ， 如 果 你 的 LDAP 服 务 器 在 男 一 台 机 器 上 ， 那 么 可 
以 使 用 contextSource() 方 法 来 配置 这 个 地 址 : 





QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 
auth 
.ldapAuthentication() 
.USerSearchBase("ou=people") 
.USerSearchFilter("(uid={06})") 
.groupSearchBase("ou=groups") 
.groupSearchFilter("member={06}") 
.passwordCompare'( ) 
.passwordEncoder(new BCryptPasswordEncoder( ) ) 
.passwordAttribute("passcode") 
.ContextSourcel) 


.Url("ldap://tacocloud.com:389/dc=tacocloud,dc=com" ); 





contextSource() 方 法 会 返回 一 个 ContextSourceBuilder 对 象 ， 这 个 对 
象 除了 其 他 功能 以 外 ， 还 提供 了 url0 方 法 来 指定 LDAP 服 务 器 的 地 址 。 


配置 家 入 式 的 LDAP 服 务 器 


如 有 果 你 没有 现成 的 LDAP 服 务 占 供认 证 使 用 ，Spring Security 还 为 我 
们 提供 了 骸 入 式 的 LDAP 服 务 器 。 我 们 不 再 需要 设置 远程 LDAP 服 务 器 
的 URL， 只 需 通过 rootO) 方 法 指定 通 入 趟 服务 需 的 根 前 缀 项 可 以 了 : 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 
auth 
.ldapAuthentication() 
.USerSearchBase("ou=people") 
.USerSearchFilter("(uid={06})") 


.groupSearchBase("ou=groups") 

.groupSearchFilter("member={6}") 

.passwordCompare'( ) 

.passwordEncoder(new BCryptPasswordEncoder()) 

.passwordAttribute("passcode") 

.ContextSourcel) 
.root("dc=tacocloud,dc=com" ); 





当 LDAP 服 务 颖 局 动 时 ， 它 会 笑 试 在 类 路 任 下 寻找 LDIF 文 件 来 加 载 
数据 。LDIF (LDAP Data Interchange Format，LDAP 数 据 交 换 格 式 ) 是 
以 文本 文件 展现 LDAP 数 据 的 标准 方式 。 每 条 记录 可 以 有 一 行 或 多 行 ， 
每 项 包 侣 一 个 name:value 配 对 信息 。 记 了 录 之 间 通 过 空 行 进行 分 割 。 


如 果 你 不 想 让 Spring 从 整个 根 路 径 下 搜索 LDIF 文 件 ， 那 么 可 以 通过 


调用 ldifO 方 法 来 明确 指定 加 载 哪个 LDIFE 文 件 : 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 
throws Exception { 
auth 
.ldapAuthentication() 
.USerSearchBase("ou=people") 
.UsSerSearchFilter("(uid={6})") 
.groupSearchBase("ou=groups") 


.groupSearchFilter("member={06}") 
.passwordCompare'( ) 
.passwordEncoder(new BCryptPasswordEncoder()) 
.passwordAttribute("passcode") 
.ContextSourcel) 
.root("dc=tacocloud,dc=com") 
.ldif("classpath:users.1dif"); 





在 这 里 ， 我 们 明确 要 求 LDAP 服 务 右 从 类 路 径 根 目 孙 下 的 users.ldif 
文件 中 加 载 内 容 。 如 果 你 比较 好 奇 ， 如 下 束 是 一 个 包 人 名 用户 数据 的 
LDIF 文 件 ， 我 们 可 以 使 用 它 来 加 载 骨 入 式 LDAP 服 务 器 : 


dn: ou=groups,dc=tacocloud,dc=com 
objectclass: top 

objectclass: organizationalUnit 

ou: groups 

dn: ou=people,dc=tacocloud,dc=com 
objectclass: top 

objectclass: organizationalUnit 

ou: people 

dn: uid=buzz,ou=people,dc=tacocloud,dc=com 
objectclass: top 

objectclass: person 

objectclass: organizationalPerson 
objectclass: inetOrgPerson 

cn: Buzz Lightyear 

sn: Lightyear 

uid: buzz 

userPassword: password 

dn: cn=tacocloud,ou=groups,dc=tacocloud,dc=com 
objectclass: top 


objectclass: groupOfNames 
cn: tacocloud 
member: uid=buzz,ou=people,dc=tacocloud,dc=com 





Spring Security 内 置 的 用 户 和 存储 非常 便利 ， 并 且 泣 六 了 最 为 汗 用 有 风 
用 户 场 景 。 但 是 ， 我 们 的 Taco Cloud 应 用 需要 一 些 特殊 的 功能 。 当 开 箱 
即 用 的 用 己 存 储 无 法 满足 需求 的 时 候 ， 我 们 束 需 要 创建 和 配置 自 定义 的 
用 户 详情 服务 。 


4.2.4 ” 目 定 义 用 户 认 证 


在 上 一 半 中 ， 我 们 采用 Spring Data JPA 作 为 所 有 taco、 配 料 和 订单 
数据 的 持久 化 方案 。 所 以 ， 采 用 相同 的 方式 来 持久 化 用 户 数据 是 非常 有 
意义 的 。 如 来 这 样 做 ， 数 据 了 最 终 应 该 位 于 关系 型 数据 库 之 中 。 因 此 ， 我 
们 可 以 使 用 基于 JDBC 的 认证 ， 但 更 好 的 办 法 是 使 用 Spring Data 
repository 来 存储 用 户 。 


要 事 优 先 ， 在 此 之 前 ， 我 们 首先 要 创建 领域 对 象 ， 以 及 展现 和 持久 
化 用 户 信 息 的 repository 接 口 。 


定义 用 尸 领域 对 象 和 持久 化 


当 Taco Cloud 的 顾客 注册 应 用 的 时 候 ， 它 们 需要 提供 除 用 记名 和 和 密 
伺 之 外 的 更 多 信息 。 人 他们 会 提供 全 名 、 地 址 和 电话 号 码 。 这 些 信 息 可 以 
用 于 各 种 目的 ， 包 括 预先 填充 表单 〈 更 不 用 说 湾 在 的 市 场 销售 机 会 ) 。 


为 了 捕获 这 些 信息 ， 我 们 要 创建 程序 清单 4.5 所 示 的 User 类 : 


程序 清单 4.5 ”定义 用 户 实体 


package tacos; 


import 
import 
import 
import 
import 
import 
import 
import 


import 
import 
import 
import 
import 


@EnNntity 


@Data 


Java.util.Arrays; 

Java.util.Collection; 

Javax.persistence.Entity; 

Javax.persistence.GeneratedValue; 

Javax.persistence.GenerationType; 

Javax.persistence.Id; 

org.springframework.security.core.GrantedAuthority; 

org.springframework.security.core.authority. 
SimpleGrantedAuthority; 

org.springframework.security.core.userdetails.UserDetails; 

lombok.AccessLevel; 

lombok .Data; 

lombok.NoArgsConstructor.,; 

Jombok .RequlIredArgsConstructor ; 


QNoArgsConstructor(access=AccessLevel .PRIVATE, force=true) 
QRequiredArgsConstructor 


public 


class User implements UserDetails { 


private static final long serialVersionUID = 1L; 


@Id 


@QGeneratedValue(strategy=GenerationType.AUTO) 
private Long id; 


private final String Username ; 
private final String password ; 
private final String fullname; 
private final String street; 
private final String city; 
private final String state; 
private final String zip; 

private final String phoneNumber ; 


QOverride 
public Collection<? extends GrantedAuthority> getAuthorities() { 
return Arrays.asList(new SimpleGrantedAuthority("ROLE USER")); 


} 


QOverride 
public boolean isAccountNonExpired() { 
return 七 Aue ; 


} 


QOverride 
public boolean isAccountNonLocked() { 
return 七 Aue ; 


} 


QOverride 
public boolean isCredentialsNonExpired() { 
return 七 Aue ; 


} 


QOverride 
public boolean isEnabled() { 
return true,; 


} 





你 可 能 也 发 现 了 ，User 类 要 比 第 3 章 所 定义 的 实体 都 更 加 复杂 。 除 
了 定义 了 一 些 属性 之 外 ，User 类 还 实现 了 Spring Security 的 UserDetails 接 
Es 


通过 实现 UserDetails 接 口 ， 我 们 能 够 提供 更 多 信息 给 框架 ， 比 如 用 
户 都 被 授予 了 哪些 权限 以 及 用 户 的 账号 是 人 否 可 用 。 


getAuthorities(0) 方 法 应 该 返回 用 户 被 授予 权限 的 一 个 集合 。 各 种 is... 
Expired() 方 法 要 返回 一 个 boolean 值 ， 表 明 用 户 的 账号 是 否 可 用 或 过 期 。 


对 于 User 实 体 来 说 ，getAuthorities0) 方 法 只 是 简单 地 返回 一 个 集 
合 ， 这 个 集合 表明 所 有 的 用 户 都 被 授予 了 ROLE_USER 权 限 。 全 少 现 现 
在 来 说 ，Taco Cloud 没 有 必要 禁用 用 户 ， 所 以 所 有 有 的 is...Expired() 方 法 均 
返回 true， 表 明 用 户 古 处 于 活跃 状态 的 。 


User 实 体 定义 完 之 后 ， 我 们 就 可 以 定义 repository 接 口 了 : 





package tacos.data; 
Import org.springframework.data.repository.CrudRepository ; 
import 七 acos .USser ; 


public interface UserRepository extends CrudRepository<User, Long> { 


User findByUsername(String username); 





除了 扩展 CrudRepository 所 得 到 的 CRUD 操 作 之 外 ，UserRepository 
接口 还 定义 了 一 个 findByUsername0) 方 法 《将 会 在 用 户 详情 服务 中 用 
到 ， 以 便于 根据 用 户 名 得 找 User) 。 


束 像 我 们 在 第 3 划 中 所 学 到 的 那样 ，Spring Data JPA 会 在 运行 时 目 
动 生 成 这 个 接口 的 实现 。 所 以 ， 我 们 现在 束 可 以 编写 使 用 该 repository 的 
用 户 评 情 接 口 了 。 





创建 用 户 详情 服务 


Spring Security 的 UserDetailsService 是 一 个 相当 人 简单 直接 的 接口 : 


public interface UserDetailsService 1{ 
UserDetails loadUserByUsername(String username) 


throws UsernameNotFoundException; 





正如 我 们 所 看 到 的 ， 这 个 接口 的 实现 会 得 到 一 个 用 户 的 用 户 名 ， 并 
且 要 么 返回 得 找到 的 UserDetails 对 象 ， 要 么 在 根据 用 户 名 无 法 得 到 任 
何 结果 的 情况 下 抛 出 Username NotFoundException。 


为 我 们 的 User 类 实现 了 UserDetails， 并 有 日 UserRepository 提 供 了 


findByUsername() 方 法 ， 所 以 它们 非常 适合 用 在 UserDetailsService 实 现 
中 。 程 序 清单 4.6 展 现 了 Taco Cloud 应 用 中 将 会 用 到 的 用 户 详 情 服务 。 


程序 清单 4.6 ”声明 目 定 义 的 用 户 详情 服务 


package tacos.security; 

import org.springframework.beans.factory.annotation.Autowired; 

import org.springframework.security.core.userdetails.UserDetails; 

import org.springframework.security.core.userdetails. 

UserDetailsService; 

import org.springframework.security.core.userdetails. 
UsernameNotFoundException; 

import org.springframework.stereotype.Service; 


import tacos.User; 

Import tacos.data.UserRepository; 

QService 

public class UserRepositoryUserDetailsService 
ijmplements UserDetailsService 1{ 


private UserRepository UserRepo ; 


QAutowired 
public UserRepositoryUserDetailsService(UserRepository userRepo) { 
this.userRepo = UserRepo ; 


} 


QOverride 
public UserDetails loadUserByUsername(String username) 
throws UsernameNotFoundException { 
User user = userRepo.findByUsername(username); 
if (user != null) { 
return USer ; 
} 
throw new UsernameNotFoundException( 
"User '" + Username + "' not found"); 





UserRepositoryUserDetailsService 通 过 构造 套 将 UserRepository 广 入 
进来 。 然 后 ， 在 loadByUsername() 方 法 中 ， 它 调用 了 UserRepository 的 


findByUsername() 方 法 来 查找 User。 


loadByUsername() 方 读 有 一 个 简单 的 规则 : 它 决 不 能 返回 null。 
此 ， 如 果 调 用 findByUsername0O 返 回 null， 那 么 loadByUsername0O 将 会 抛 


出 UsernameNotFoundException; 否则， 将 会 返回 得 找到 的 User。 


我 们 注意 到 UserRepositoryUserDetailsService 上 添加 了 @Service。 这 
是 Spring 的 另外 一 个 构造 型 〈stereotype) 注解 ， 它 表明 这 个 类 要 包含 到 
Spring 的 组 件 扫 摘 中 ， 所 以 我 们 不 需要 再 明确 将 这 个 闫 声明 为 bean 了 。 
Spring 将 会 目 动 及 现 它 并 将 其 初始 化 为 一 个 bean。 


但 是 ， 我 们 依然 需要 将 这 个 目 定 义 的 用 户 详情 服务 与 Spring 
Security 配 置 在 一 起 。 因 此 ， 我 们 再 次 回 到 configure() 方 法 : 


QAutowired 
private UserDetailsService userDetailsService; 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 


throws Exception { 


auth 
.USerDetailsService(userDetailsService); 





在 这 里 ， 我 们 只 是 简单 地 调用 userDetailsService() 方 法 ， 并 将 自动 装 
配 到 SecurityConfig 中 的 UserDetailsService 实 例 传 递 了 进去 。 


像 基于 JDBC 的 认证 一 梓 ， 我 们 可 以 “也 应 该 ) 配置 一 个 蜜 但 园 码 
名 ， 这 样 在 数据 库 中 的 密码 将 是 转 码 过 的 。 我 们 首先 需要 声明 一 个 


PasswordEncoder 类 型 的 bean， 然 后 通过 调用 passwordEncoder0) 方 法 将 它 
注入 到 用 户 详情 服务 中 : 


QBean 
public PasswordEncoder encoder() { 
return new StandardPasswordEncoder("53cr3t"); 


} 


QOverride 
protected void configure(AuthenticationManagerBuilder auth) 


throws Exception { 


auth 
.USerDetailsService(userDetailsService) 
.passwordEncoder(encoder()); 





我 们 讨论 一 下 configure() 方 法 中 比较 重要 的 最 后 一 行 。 看 上 去 ,我 
们 调用 了 encoder0) 方 法 ， 并 将 返回 值 传递 给 passwordEncoder0。 实 际 
上 ，encoder0) 方 法 市 有 @Bean 注 解 ， 它 将 用 来 在 Spring 应 用 上 下 文中 声 
明 PasswordEncoder bean。 对 于 encoder0 的 任何 调用 都 会 被 拦截 ， 并 且 会 
返回 应 用 上 下 文中 的 bean 实 例 。 


现在 ， 我 们 已 经 有 了 上 自 定义 的 用 户 详 情 服 务 ， 它 会 通过 JPA 
repository 谈 取 用 户 信 息 ， 接 下 来 我 们 需要 一 种 将 用 户 存 放 到 数据 库 中 的 
办 法 。 为 了 做 到 这 一 点 ， 我 们 需要 为 Taco Cloud 创 建 一 个 注册 页 面 ， 供 
用 户 注 册 本 应 用 。 
注册 用 户 


尽管 在 安全 性 方面 ，Spring Security 会 为 我 们 处 理 很 多 事情 ， 但 是 


它 没有 直接 涉及 用 户 注 册 的 流程 ， 所 以 我 们 需要 借助 Spring MVC 的 一 些 
技能 来 完成 这 个 任务 。 程 序 清单 4.7 所 示 的 RegistrationController 关 会 负 
责 展 现 和 处 理 注 册 表 单 。 


程序 清单 4.7 ”用户 注册 控制 右 


package tacos.security; 

Import org.springframework.security.crypto.password.PasswordEncoder.,; 
Import org.springframework.stereotype.Controller.; 

Import org.springframework.web.bind.annotation.GetMapping; 

Import org.springframework.web.bind.annotation.PostMapping; 

import org.springframework.web.bind.annotation.RequestMapping; 
Import tacos.data.UserRepository; 


@Controller 

@QRequestMapping("/register") 

public class RegistrationController { 
private UserRepository UserRepo ; 
private PasswordEncoder passwordEncoder ; 


public RegistrationController( 
UserRepository userRepo, PasswordEncoder passwordEncoder) { 


this.userRepo = UserRepo ; 
this.passwordEncoder = passwordEncoder; 


} 


Q@QGetMapping 
public String registerForm() { 
return “registration",; 


} 


QPostMapping 

public String processRegistration(RegistrationForm form) { 
userRepo.save(form.toUser(passwordEncoder ) ) ; 
return “ redirect:/ Loglin 


} 





与 很 多 典型 的 Spring MVC 控 制 右 英 似 ，RegistrationController 使 用 
@Controller 注 解 表明 它 是 一 个 控制 右 ， 并 且 人 多 许 组 件 扫 摘 功能 发 现 它 。 


它 还 使 用 了 @RequestMapping 注 艇 ， 这 样 罗 能 处 理 路 径 为 “register” 的 请 
求 了 。 有 具体 来 计 ， 对 “/register” 的 GET 请 求 会 由 registerForm() 方 法 来 处 
理 ， 它 只 是 简单 地 返回 一 个 锡 辑 视图 名 registration。 程 序 清 单 4.8 展 现 了 
定义 registration 视 图 的 Thymeleaf 模 板 。 


程序 清单 4.8 注册 表单 的 Thymeleaf 视 图 


<1DOCTYPE html> 
<html xmlns="http://www.w3.org/1999/xhtml" 
xmlns:th="http://www.thymeleaf.org"> 
<head> 
<title>Taco Cloud</title> 
</head> 


<body> 
<h1i>Register</hi1> 
<img th:src="Q@{/images/TacoCloud.png}"/> 


<form method="POST" th:action="@{/register}" id="registerForm"> 


<label for="username">Username: </label> 
<input type= text name= Username /><br/ > 


<label for= password >Password: </label> 
<input type= password name= password /><br/> 


<label for="confirm">Confirm password: </label> 
<input type="password" name="confirm'"/><br/> 


<label for="fullname">Full name: </label> 
<input type= text name="fullname"/><br/> 


<label for="street">Street: </label> 
<input type= text name="street"/><br/> 


<label for="city">City: </label> 
<input type="text" name="city"/><br/> 


<label for= state >State: </label> 
<input type= text ”name= State /><br/> 


<label for="zip">Zip: </label> 


<input type= text ”name= Z1Ip /><br/> 


<label for= phone >Phone: </label> 
<input type= text ”name= phone /><br/ > 


<input type= Submit ”Value= Reglster /> 
</form> 


</body> 


</html> 





当 表 早 提 交 的 时 候 ，processRegistration() 方 法 会 处 理 HTTP POST 请 
求 。ProcessRegistration0) 方 法 得 到 的 RegistrationForm 对 象 绑 定 了 请 求 的 
数据 ， 访 美的 定义 如 下 : 


package tacos.security; 

Import org.springframework.security.crypto.password.PasswordEncoder.; 
Import Lombok .Data 

Import tacos.User ; 


@Data 
public class RegistrationForm { 


private String username,; 
private String password; 
private String fullname; 
private String street; 
private String city; 
private String state; 
private String zip; 
private String phone; 


public User toUser(PasswordEncoder passwordEncoder) { 
return new User( 
username, passwordEncoder.encode(password), 
fullname, street, city, state, zip, phone); 





束 其 大 部 分 内 容 而 言 ，RegistrationForm 束 是 一 个 简 早 的 支持 


Lombok 类 ， 上 有 具有 一 些 相 关 的 属性 。 但 是 ，toUser() 方 法 使 用 这 些 属性 创 
建 了 一 个 新 的 User 对 象 ，processRegistration() 使 用 注入 的 UserRepository 
保存 了 该 对 象 。 


你 肯定 已 经 发 现 RegistrationController 注 入 了 一 个 PasswordEncoder,， 
这 其 实 就 是 我 们 在 前 面 所 声明 的 PasswordEncoder。 在 处 理 表 单 提交 的 时 
候 ，RegistrationController 将 其 传递 给 toUser0 方 法 ， 在 将 密码 保存 到 数 
据 库 之 前 ， 会 使 用 它 对 和 密码 进行 转 码 。 通 过 这 种 方式 ， 用 户 的 密码 可 以 
以 转 公 后 的 形式 写 入 到 数据 库 中 ， 用 户 详 情 服 务 束 能 基于 转 人 码 后 的 和 窒 公 
对 用 户 进行 认证 了 。 

现在 ，Taco Cloud 应 用 已 经 有 了 完整 的 用 户 注 册 和 认证 蕊 能。 但 
AGRI 也 不 会 拓 

进行 登录 。 这 是 因为 在 默认 情况 下 ， 所 有 的 请 求 部 需要 认证 。 接 下 


网 我 们 看 一 下 Web 请 求 是 如 何 补 拦截 和 保护 的 ， 这 样 我 们 才能 解决 这 
个 先 有 鸡 还 是 先 有 和 集 的 诡异 问题 。 


4.3 ”保护 Web 请 求 


Taco Cloud 的 安全 性 需求 是 用 户 在 设计 taco 和 提交 订单 之 前 必须 要 
经 过 认证 。 但 是 ， 主 页 、 登 录 页 和 注册 页 应 该 对 未 认证 的 用 户 开 放 。 


为 了 配置 这 些 安全 性 规则 ， 需 要 介绍 一 下 
WebSecurityConfigurerAdapter 的 其 他 configure0) 方 法 : 


override | 


protected void configure(HttpSecurity http) throws Exception { 
} 


configure() 方 法 接受 一 个 HttpSecurity 对 象 ， 能 够 用 来 配置 在 Web 级 
列 访 如 何 处 理 安全 性 。 我 们 可 以 使 用 HttpSecurity 配 置 的 功能 包括 : 


。 在 为 东 个 请 求 提供 服务 之 前 ， 需 要 预先 满足 特定 的 条 件 ; 
配置 目 定义 的 登录 页 ; 

。 文 持 用 户 退 出 应 用 : 

预防 路 站 请 求 伪 造 。 


配置 HttpSecurity 第 见 的 需求 就 是 拦截 请 求 以 确保 用 户 上 有 具备 适 当 的 权 
限 。 接 下 来 ， 我 们 会 确保 Taco Cloud 的 顾客 能 够 满足 这 些 需求 。 


4.3.1 ”保护 请 求 


我 们 需要 确保 只 有 认证 过 的 用 户 才 能 及 起 对 “design” 和 “orders” 的 
请 求 ， 而 其 他 请 求 对 所 有 用 户 均 可 用 。 如 下 的 configureO 实 现 就 能 实现 


QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 


.authorizeRequests'( ) 
.antMatchers("/design", "/orders") 
.hasRole("ROLE USER") 
.antMatchers(“/”, "/**").permitAll() 





对 authorizeRequestsO 的 调用 会 返回 一 个 对 象 


(ExpressionInterceptUrlRegistry) ， 基 于 它 我 们 可 以 指定 URL 路 人 和 任 和 这 
些 路 径 的 安全 需求 。 在 本 例 中 ， 我 们 指定 了 两 条 安全 规则 : 


。 具备 ROLE_USER 权限 的 用 户 才 能 访问 “design” 和 ”“/orders”; 
e。 其 他 的 请 求人 允许 所 有 用 户 访问 。 


这 些 规 则 的 顺序 是 很 重要 的 。 声 明 在 前 面 的 安全 规则 比 后 面 声明 的 
规则 有 更 高 的 优先 级 。 如 采 我 们 交换 这 两 个 安全 规则 的 顺序 ， 那 么 所 有 
的 请 求 都 会 有 permitAl10O 的 规则 ， 对 “design” 和 “orders” 声 明 的 规则 残 不 
会 生效 了 。 


在 声明 请 求 路 径 的 安全 需求 时 ，hasRole0 和 permitAl1O 只 是 众多 方 
法 中 的 两 个 。 表 4.1 列 出 了 所 有 可 用 的 方法 。 


表 4.1 用 来 定义 如 何 保护 路 径 的 配置 方法 


如 果 给 定 的 SPEL 表 达 式 计算 结果 为 tue， 束 允许 访问 


允许 认证 过 的 用 户 访 问 
无 条 件 拒 绝 所 有 访问 


如 果 用 户 是 完整 认证 的 (不 是 通过 Remember-me 功 能 认证 





fullyAuthenticated() 的 ) ， 束 允许 访问 





hasAnyAuthority(String.…) | 如果 用 户 共 备 给 定 权 限 中 的 有 霖 一个， 焉 允许 访问 


如 果 用 性 具备 给 定 角 色 中 的 东 一 个 ， 束 允许 访问 





如 果 用 户 具 备 给 定 权限 ， 束 允许 访问 

如 果 请 求 来 自给 定 卫 地 址 ， 就 允许 访问 

如 琳 用 户 有 具备 给 定 角色 ， 残 允许 访问 

对 其 他 访问 方法 的 结 末 求 反 

如 果 用 户 是 通过 Remember-me 功 能 认证 的 ， 就 允许 访问 


表 4.1 中 的 大 多 数 方法 为 请 求 处 理 提 供 了 基本 的 安全 的 规则 ， 但 它 
们 十 目 我 限制 的 ， 也 吏 是 只 能 文 持 由 这 些 方法 所 定义 的 安全 规则 。 除 此 
之 外 ， 我 们 还 可 以 使 用 access0) 方 法 ， 通 过 为 其 提供 SpEL 表 达 陈 来 声明 
更 丰 宦 有 的 安全 规则 。Spring Security 扩 展 了 SpEL， 包 含 了 多 个 安全 相关 
的 值 和 函数 ， 如 表 4.2 所 示 。 








表 4.2 Spring Security 对 Spring 表 达 式 语言 的 扩展 


authentication 


denyAll 


hasAnyRolel(list of 


roles) 


hasRole(role) 


hasIpAddress(IP 
Address) 


isAnonymous() 


isAuthenticated() 


isFullyAuthenticated() 


isRememberMe() 


permitAll 


principal 


用 户 的 认证 对 象 





结果 始终 为 false 


如 条 用 户 被 授予 了 列表 中 任意 的 指定 角色 ， 结 东 为 true 





如 果 用 户 被 授予 了 指定 的 角色 ， 绪 来 为 true 


如 果 请 求 来 自 指 定 IP， 结 果 为 true 





如 朱 当 前 用 户 为 匿名 用 户 ， 结 条 为 true 


如 果 当 前 用 户 进行 了 认证 ， 结 果 为 true 


如 果 当 前 用 户 进行 了 完整 认证 〈 不 是 通过 Remember-me 功 能 进 
行 的 认证 ) ， 结 果 为 true 


如 果 当 前 用 户 是 通过 Remember-me 目 动 认 证 的 ， 结 果 为 true 


结果 始终 为 true 


用 户 的 principal 对 象 


| 


我 们 可 以 看 到 ， 表 4.2 中 大 多 数 的 安全 规则 部 对 应 表 4.1 中 类 似 的 方 
法 。 实 际 上 ， 借 助 access() 方 法 和 hasRole()、permitAll 表 达 式 ， 我 们 可 以 
将 configure0O 重 写 为 程序 清单 4.9 所 示 的 形 却 : 


程序 清单 4.9 使 用 Spring 表达 式 来 定义 认证 规则 


QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 
.authorizeRequests'( ) 


.antMatchers("/design", "/orders") 
.access("hasRole('ROLE USER')") 
.antMatchers(“/”, "/**").access("permitAll") 





看 上 去 ， 这 似乎 也 没什么 大 不 了 了 的。 毕竟， 这 些 表达 式 只 是 模拟 了 
我 们 之 前 通过 方法 调用 已 经 完成 的 事情 。 但 是 ， 表 达 式 可 以 更 加 灵活 。 
例如 ， 假 设 〈 基 于 某 些 状 狂 的 原因 ) 我们 只 允许 具备 ROLE_USER 权 限 
的 用 户 在 星期 二 创建 新 taco〈 我 们 可 以 将 其 称 为 Taco Tuesday) ， 这 样 
束 可 以 午 写 表达 式 。 如 下 的 代码 展现 了 已 修改 的 configure(): 


QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 
.authorizeRequests'( ) 
.antMatchers("/design", "/orders") 
.acCcess("hasRole('ROLE USER') && ”+ 


"T(java.util.Calendar).getInstance().get("+ 

"T(java.util.Calendar).DAY OF WEEK) == ”+ 

"T(java.util.Calendar) .TUESDAY") 
.antMatchers(“/”, "/**").access("permitAll") 





我 们 可 以 使 用 SpEL 实 现 各 种 各 样 的 安全 性 限制 。 我 敢 打 财 ， 你 已 
经 在 想象 基于 SpEL 所 能 实现 的 那些 有 趣 的 安全 性 限制 了 。 


Taco Cloud 应 用 的 权限 可 以 通过 简单 使 用 access0 和 SpEL 表 达 陈 来 实 
现 ， 如 程序 清单 4.9 所 示 。 现 在 ， 我 们 看 一 下 如 何 目 定义 登录 页 以 适应 
Taco Cloud 应 用 的 外 观 。 


4.3.2 ”创建 目 定 义 的 登录 页 


默认 的 登录 页 已 经 比 最 初 丑 陋 的 HITP basic 认 证 对 话 框 好 了 很 多 ， 
但 是 它 依然 非常 简单 ， 并 且 与 Taco Cloud 应 用 其 他 部 分 的 外 观 不 搭配 。 


为 了 将 换 内 置 的 登录 页 ， 我 们 首先 需要 和 岩 诉 Spring Security 目 定义 
登录 页 的 路 径 是 什么 。 这 可 以 通过 调用 传 入 到 configureO 中 的 
HttpSecurity 对 象 的 formLogin0 方 法 来 实现 : 


QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 
.authorizeRequests'( ) 
.antMatchers("/design", "/orders") 
.access("hasRole('ROLE USER')") 


.antMatchers(“/”, "/**").access("permitAll") 


.and() 
.formLogin() 
.loginpage("/login") 





请 注意 ， 在 调用 formLogin0 之 前 ， 我 们 通过 and0 方 法 将 这 一 部 分 的 
配置 与 前 面 的 配置 连接 在 一 起 。and0) 方 法 表示 我 们 已 经 完成 了 授权 相关 


的 配置 ， 并 且 要 添加 一 些 其 他 的 HITP 配 置 。 在 开始 新 的 配置 区 域 时 ， 
我 们 可 以 多 次 调用 and()。 


在 这 个 连接 之 后 ， 我 们 调用 formLogin0 开 始 配置 自 定 义 的 登录 表 
单 。 在 此 之 后 ， 对 loginPage0 的 调用 声明 了 我 们 提供 的 目 定 义 登 录 页 面 
的 路 径 。 当 Spring Security 断 定 用 户 没 有 认证 并 且 需 要 登录 的 时 候 ， 它 
惑 会 将 用 刀 重 定 同 到 该 路 径 。 


现在 ， 我 们 需要 有 一 个 控制 颖 来 处 理 对 设 路 任 的 请 求 。 因 为 我 们 的 
登录 页 非 关 和 侧 单 ， 只 有 一 个 视图 ， 没 有 其 他 内 容 ， 所 以 我 们 可 以 很 简单 
地 在 WebConfig 中 将 其 声明 为 一 个 视图 控制 亚 。 在 映射 到 “的 主页 控制 
器 基础 之 上 ， 如 下 的 addViewControllers(0) 方 法 声明 了 登录 页 面 的 视图 控 
制 | 其: 


QOverride 
public void addViewControllers(ViewControllerRegistry registry) { 


registry.addViewController("/").setViewName("home"); 
registry.addViewController("/login"); 





取 后 ， 我 们 需要 目 己 定义 登录 由 的 视图 。 我 们 目前 使 用 了 
Thymeleaf 作 为 模板 引擎 ， 所 以 如 下 的 Thymeleaf 就 能 实现 我 们 的 要 求 : 





<1DOCTYPE html> 
<html xmlns="http://www.w3.org/1999/xhtml" 
xmlns:th="http://www.thymeleaf.org"> 
<head> 
<title>Taco Cloud</title> 
</head> 


<body> 
<h1i>Login</h1> 
<img th:src="Q@{/images/TacoCloud.png}"/> 


<div th:if="${error}"> 
Unable to login. Check your username and password. 
</div> 


<p>New here? Click 
<a th:href="@{/register}">here</a> to register.</p> 


<!-- tag::thAction[| --> 
<form method="POST" th:action="@{/login}" id="loginForm"> 
<!-- end::thAction[| --> 
<label for="username">Username: </label> 
<input type= text ”name= Username ”1Id= Username ”/><br/> 
<label for= password >Password: </label> 
<input type= password ”name= password 1d= password /><br/> 


<input type= Submit ”Value= Logln /> 
</form> 


</body> 
</html> 


这 个 登录 页 需要 关注 的 事情 就 是 表单 提交 到 了 什么 地 方 以 及 用 户 名 
和 和 密码 输入 域 的 名 称 。 默 认 情 况 下 ，Spring Security 会 在 %login” 路 径 监 
听 登 录 请 求 并 且 预 期 的 用 户 名 和 密码 输入 域 的 名 称 为 username 和 
password。 但 这 都 是 可 配置 的 ， 举 例 来 说 ， 如 下 的 配置 目 定 义 了 路 径 和 
答 入 域 的 名 称 ; 
.and ( ) 


.formLogin() 
.loginpage("/login") 


.loginprocessingUrl("/authenticate") 
.USsernameParameter("user") 
.passwordParameter("pwd") 





在 这 里 ， 我 们 声明 Spring Security 要 监听 对 “/authenticate” 的 请 求 来 
处 理 登 录 信 息 的 提交 。 同 时 ， 用 户 名 和 签 人 码 的 字段 名 应 该 是 user 和 
pwd。 


堆 认 情况 下 ， 登 录 成 功 之 后 ， 用 户 将 会 被 导航 到 Spring Security 决 
定 让 用 户 和 登录 之 前 的 页 面 。 如 各 用 户 下 接 访 问 登 录 页 ， 那 么 登录 成 功 之 
后 用 户 将 会 被 导航 至 根 路 径 《〈 例 如 ， 主 页 ) 。 但 是 ， 我 们 可 以 通过 指定 
堆 认 的 成 功 页 来 更 改 这 种 行为 : 


.and ( ) 
.formLogin() 


.loginpage("/login") 
.defaultSuccessUrl("/design") 





按照 这 个 配置 ， 用 户 直 接 导 航 至 登录 页 并 且 成 功 登 录 之 后 将 会 被 定 
加 到 “design” 页 面 。 


另外 ， 我 们 还 可 以 强制 要 求 用 户 在 登录 成 功 之 后 统一 访问 设计 页 
面 ， 即 便 用 户 在 登录 之 前 正在 访问 其 他 页 面 ， 在 登录 之 后 也 会 被 定 癌 到 
设计 页 面 ， 这 可 以 通过 为 defaultSuccessUrl 方 法 传递 第 二 个 参数 true 来 实 
现 : 


.and() 
.formLogin() 


.loginpage("/login") 
.defaultSuccessUrl("/design", true) 





现在 ， 我 们 已 经 完成 了 目 定 义 的 登录 页 面 ， 接 下 来 我 们 关注 认证 功 
能 的 万 一 面 ， 那 吏 定 如 何 让 用 户 退 出 应 用 。 


4.3.3 ”退出 


退出 和 应 用 的 登录 是 同等 重要 的 。 为 了 局 用 退出 功能 ， 我 们 只 需 在 


HttpSecurity 对 象 上 调用 logout 方 法 : 


.and () 
.logout() 
.logoutSuccessUr1("/") 


这 样 会 搭建 一 个 安全 过 滤 磅 ， 访 过 小 右 会 拦截 对 “/logout” 的 请 求 。 
所 以 ， 为 了 提供 退出 功能 ， 我 们 需要 为 应 用 的 视图 添加 一 个 退出 表单 和 
按钮 : 


<form method=" POST” th:action="@{/logout}"> 


<input type= Submilit ”Value= Logout /> 
</form> 





当 用 户 点 击 按钮 的 时 候 ， 他 们 的 Session 将 会 被 清理 ， 这 样 他 们 束 退 
出 应 用 了 。 默 认 情 况 下 ， 用 六 会 被 重 定 回 到 登录 页 面 ， 这 样 他 们 可 以 重 
新 登录 。 但 是 ， 如 末 你 想 要 将 他 们 导 央 全 不 同 的 页 面 ， 那 么 可 以 调用 
logoutSuccessUrlO 指 定 退 出 后 的 不 同 页 面 : 


.and () 
.logout() 
.logoutSuccessUr1("/") 


在 本 例 中 ， 用 户 在 退出 之 后 将 会 回 到 主页 。 
4.3.4 ”防止 跨 站 请 求 伪造 
跨 站 请 求 伪 造 (Cross-Site Request Forgery，CSRF) 是 一 种 稼 见 的 


安全 攻击 。 它 会 让 用 户 在 一 个 恶意 的 Web 页 面 上 填写 信息 ， 然 后 目 动 
( 通 第 是 秘密 的 ) 将 表 早 以 攻击 受害 者 的 里 份 提交 到 为 外 一 个 应 用 上 。 


例如 ， 用 户 看 到 一 个 来 自 攻击 者 的 Web 站 点 的 表单 ， 这 个 站 点 会 自动 将 
数据 POST 到 用 户 银行 Web 站 点 的 URL 上 〔〈 这 个 站 点 可 能 设计 得 很 粳 

糙 ， 无 法 防御 这 种 类 型 的 攻击 ) ， 实 现 转 账 的 操作 。 用 户 可 能 根本 不 知 
道 发 生 了 攻击 ， 直 到 他 们 发 现 账号 上 的 钱 已 经 不 辟 而 飞 。 


为 了 防止 这 种 类 型 的 攻击 ， 应 用 可 以 在 展现 和 表单 的 时 候 生成 一 个 
CSRF token， 并 放 到 隐 医 袁 中 ， 然 后 将 其 临时 存储 起 来 ， 以 便 后 续 在 服 
务 器 上 使 用 。 在 提交 表单 的 时 候 ，token 将 和 其 他 的 表单 数据 一 起 发 送 
全 服务 器 病 。 请 求 会 被 服务 套 拦 蕉 ， 并 与 最 初生 成 的 token 进 行 对 比 。 
如 采 token 匹 配 ， 那 么 请 求 将 会 允许 处 理 ; 否则 ， 表 单衣 定 是 由 亚 意 网 
站 渔 染 的 ， 因 为 它 不 知道 服务 器 所 生成 的 token。 


比较 邓 运 的 是 ，Spring Security 提 供 了 内 置 的 CSRF 人 保护。 更 对 和 运 的 
征 ， 默 认 它 吏 是 司 用 的 ， 我 们 不 需要 显 陈 配置 它 。 我 们 唯一 需要 做 的 驶 
是 确保 应 用 中 的 每 个 表单 都 要 有 一 个 名 为 “_csrf” 的 字段 ， 它 会 持 有 
CSRF token 。 


Spring Security 甚 至 进一步 简化 了 将 token 放 到 请 求 的 ”csrf" 属 性 中 
这 一 任务 。 在 Thymeleaf 模 板 中 ， 我 们 可 以 按照 如 下 的 方式 在 隐藏 域 中 
演 染 CSRF token: 





<input type="hidden”name=” csrf" th:value="${ csrf.token}"/> 


如 果 你 使 用 Spring MVC 的 JSP 标 俭 库 或 者 Spring Security 的 
Thymeleaf 方 言 ， 那 么 其 全都 不 用 明确 包 依 这 个 隐 蔚 域 〈《 这 个 隐 医 域 会 
目 动 生成 ) 。 


i 机 我 们 只 需要 确保 <form> 的 菏 个 属性 市 有 Thymeleaf 
属性 前 级 即 可 。 通 第 这 并 不 是 什么 问题 ， 因 为 我 们 一 般 会 使 用 
Tole 上 下 文 的 路 和 任 。 例 如 ， 为 了 让 Thymeleaf 泻 染 隐 中 
域 ， 我 们 只 需要 使 用 th:action 属 性 就 可 以 了 : 





<form method="POST"” th:action="@{/login}" id="loginForm"> 


我 们 还 可 以 禁用 Spring Security 对 CSRF 的 文 持 ， 但 是 我 很 犹豫 是 
要 为 你 们 展现 这 个 功能 a 
实现 ， 所 以 我 们 没有 理由 禁用 它 。 但 是 ， 如 果 你 坚持 要 禁用 ， 那 么 可 以 
通过 调用 disable() 来 实现 : 
.and() 


.CSrf() 
.disablel() 


再 次 强调 ， 不 要 共用 CSRF 防 护 ， 对 于 生产 环境 的 应 用 来 说 更 是 如 
ee 


Taco Cloud 应 用 所 有 Web 层 的 安全 性 都 已 经 配置 好 了 。 除 此 之 外 ， 
我 们 还 有 了 一 个 目 定义 的 登录 页 并 且 能 够 通过 基于 JPA 的 用 户 repository 
来 认证 用 户 。 接 下 来 ， 我 们 看 一 下 如 何 获 取 己 登录 用 户 的 信息 。 


4.4 了 解 用 户 是 谁 


通 币 ， 仅 仅 知 道 用 户 已 登录 是 不 够 的 ， 我 们 一 般 还 需要 知道 他 们 是 
过 


谁 ， 这 样 才能 优化 体验 。 


例如 ， 在 OrderController 中 ， 在 最 初创 建 Order 的 时 候 会 绑 定 一 个 订 
音 的 表单 ， 如 末 我 们 能 够 预先 将 用 户 的 姓名 和 地 址 填充 到 Order 中 束 好 
了 了， 这样 用 户 焉 不 需要 为 每 个 订单 都 重新 输入 这 些 信 息 了 。 也 许 更 重要 
的 是 ， 在 保存 订单 的 时 候 应 该 将 Order 实 体 与 创建 该 订单 的 用 户 关 联 起 
小 


为 了 在 Order 实 体 和 User 实 体 之 则 实现 所 需 的 关联， 我 们 需要 为 
Order 类 添加 一 个 新 的 属性 : 


@Data 

@EnNtity 

@Table(name="Taco Order") 

public class Order implements Serializable { 


QManyToOne 
private User USser ; 





这 个 属性 上 的 @ManyTooOne 广 解 表 明 一 个 订单 只 能 属于 一 个 用 户 ， 
但 是 ， 一 个 用 户 却 可 以 有 多 个 订单 。 因 为 我 们 使 用 了 Lombok， 所 以 不 
需要 为 该 属性 显 式 定义 访问 需 方 法 。 


在 OrderController 中 ，PprocessOrder0) 方 法 负责 保存 订单 。 这 个 方法 
需要 修改 以 便于 确定 当前 的 认证 用 户 是 谁 ， 并 且 要 调用 Order 对 象 的 
setUser() 方 法 来 建立 订单 和 用 户 之 间 的 关联 。 


我 们 有 多 种 方式 硝 定 用 户 是 谁 ， 第 用 的 方式 如 下 : 


注入 Principal 对 象 到 控制 硕 方 法 中 : 

注入 Authentication 对 象 到 控制 右 方 法 中 ; 

使 用 SecurityContextHolder 来 获取 安全 上 上 下文; 
使 用 @AuthenticationPrincipal 注 解 来 标注 方法 。 


举例 来 说 ， 我 们 可 以 修改 processOrder0 方 法 ， 让 它 接 受 一 个 
java.security.Principal 类 型 的 参数 。 人 然后， 我们 束 可 以 使 用 Principal 的 名 
称 从 UserRepository 中 和 查找 用 户 了 : 


QPostMapping 

public String processOrder(@Valid Order order, Errors errors, 
SessionStatus sessionStatus, 
Principal principal) { 


User user = UserRepository .findByUsername 
principal.getName() ) ; 


order.setUser(user); 





这 种 方式 能 够 正常 运行 ， 但 是 它 会 在 与 安全 无 关 的 功能 中 挫 末 安全 
性 的 代码 。 我 们 可 以 修改 processOrder0) 方 法 ， 让 它 不 再 接 有 党 Principal 参 
数 ， 而 是 接受 Authentication 对 象 作为 参数 : 





QPostMapping 

public String processOrder(@Valid Order order, Errors errors, 
SessionStatus sessionStatus, 
Authentication authentication) { 


User user = (User) authentication.getPrincipal(); 


order.setUser(user); 





有 了 Authentication 对 象 之 后 ， 我 们 束 可 以 调用 getPrincipal() 来 获取 
Principal 对 象 ， 在 本 例 中 ， 也 殉 是 一 个 User 对 象 。 需 要 注意 ， 
getPrincipal() 返 回 的 是 java.util.Object， 所 以 我 们 需要 将 其 转换 成 User。 


最 整洁 的 方 宁可 能 古 在 processOrder() 中 直接 接受 一 个 User 对 象 ， 不 
过 我 们 需要 为 其 添加 @AuthenticationPrincipal 注 解 ， 这 样 它 才 会 变 成 认 
证 的 principal: 


QPostMapping 

public String processOrder(@Valid Order order, Errors errors, 
SessionStatus sessionStatus, 
OAuthenticationPrincipal User user) { 


if (errors.hasErrors()) { 
return "orderForm"; 


} 


order .setUser(user); 


orderRepo.save(order ) ; 
sessionStatus.setComplete( ) ; 


return “redirect:/"; 





@AuthenticationPrincipal 非 党 好 的 一 点 在 于 它 不 需要 类 型 转换 (前 
文中 的 Authentication 则 逢 要 进行 类 型 转换 ) ， 同 时 能 够 将 安全 相关 的 代 
公 仪 仪 局 限于 注解 本 时 。 在 processOrder() 得 到 User 对 象 之 后 ， 我 们 就 可 
以 使 用 它 并 赋值 给 Order 了 。 


还 有 为 外 一 种 方式 能 够 识别 当前 认证 用 尸 古 谁 ， 但 是 这 种 方式 有 所 
抹 烦 ， 它 会 包含 大 量 安 全 性 相 天 的 代码 。 我 们 可 以 从 安全 上 下 文中 获取 
一 个 Authentication 对 象 ， 然 后 像 下 和 面 这 样 获取 它 的 principal: 


Authentication authentication = 


SecurityContextHolder .getContext() .getAuthentication( ) ; 
User user = (User) authentication.getPrincipal() ; 





尺 官 这 个 代 公 片段 充满 了 安全 性 相关 的 代码 ， 但 十 它 与 前 文 所 述 的 
其 他 方法 相 比 有 一 个 优势 : 它 可 以 在 应 用 程序 的 任何 地 方 使 用 ， 而 不 仅 
仅 是 在 控制 硕 的 处 理 硕 方法 中 。 这 使 得 它 非 名 适合 在 较 低 级 列 的 代码 中 
使 用 。 


4.5 小结 


。 Spring Security 的 自动 配置 是 实现 基本 安全 性 功能 的 好 办 法 ， 但 是 
大 多 数 的 应 用 都 震 要 显 式 的 安全 配置 ， 这 样 才 能 渍 中 特定 的 安全 需 
求 。 

。 用 户 详 情 可 以 通过 用 户 存 储 进 行 绾 理 ， 它 的 后 问 可 以 是 关系 型 数据 
库 、LDAP 或 完全 目 定 义 实现 。 

e。 Spring Security 会 自动 防范 CSRE 攻 击 。 

。 己 认证 用 户 的 信息 可 以 通过 SecurityContext 对 象 ( 该 对 象 可 由 
SecurityContextHolder. getContext() 返 回 〉 来 获取 ， 也 可 以 借助 
@AuthenticationPrincipal 注 解 将 其 注入 到 控制 妖 中 。 


第 5 和 草 ”使 用 配置 属性 


本 章 内 容 : 
。 细 粒 上 度 的 目 动 配置 bean 


。 将 配置 属性 用 到 应 用 组 件 上 


。 使 用 Spring profile 





你 还 记得 iPhone 刚刚 推出 时 的 场景 吗 ? 它 只 是 一 小 块 由 金属 和 玻璃 
组 成 的 板子 ， 完 全 不 符合 人 们 之 前 对 于 手机 的 认 知 。 但 是 ， 它 开创 了 现 
代 鲁 能 手机 的 时 代 ， 完 全 改变 了 通信 的 方式 。 尽 管 触 控 手机 比 上 一 代 的 
翻 址 手机 在 很 多 方面 者 更 加 简单 ， 蕊 能 也 更 强大 ， 但 是 当 iPhone 第 一 次 
肥 布 的 时 候 ， 很 难 想象 只 有 一 个 按钮 的 设备 该 如 何 用 来 打 电 话 。 


从 某 种 程度 上 来 讲 ，Spring Boot 的 自动 配置 与 之 类 似 。 自 动 配置 能 
够 极 大 地 简化 Spring 应 用 的 开发 。 十 多 年 来 ， 我 们 都 是 使 用 Spring XML 
设置 属性 值 ， 然 后 调用 bean 实 例 的 setter 方 法 ， 在 使 用 自动 配置 之 后 ， 我 
们 突然 发 现在 没有 显 陈 配置 的 情况 下 ， 如 何 为 bean 设 置 属性 变 得 不 那么 


到 而 忽 见 了 。 


羊 好 ，Spring Boot 提 供 了 配 壮 属性 (configuration property) 的 方 
法 。 其 实 ， 配 置 属性 只 是 Spring 应 用 上 下 文中 bean 的 属性 而 已 ， 它 们 可 
以 通过 多 个 源 进行 设置 ， 包 括 JVM 系 统 属性 、 命 令 行 参数 以 及 环境 变 


三 | 


人 


里 o 


在 本 章 中 ， 我 们 暂 绥 实现 Taco Cloud 应 用 的 新 特性 ， 将 目光 转向 配 
置 属性 的 功能 。 不 过 ， 当 我 们 在 后 面 的 章节 继续 实现 新 特性 时 ， 你 会 肥 
现 所 学 的 内 容 无 疑 都 是 有 用 的 。 我 们 首先 看 一 下 如 何 使 用 配置 属性 来 微 
调 Spring Boot 的 目 动 配置 。 


5.1 ” 细 交 及 的 日 动 配置 


在 深入 了 解 配置 属性 之 前 ， 我 们 需要 知道 ， 和 在 Spring 中 有 两 种 不 同 
(但 相关 )〉 的 配置 。 


e。 bean 装 配 : 声明 在 Spring 应 用 上 下 文中 创建 哪些 应 用 组 件 以 及 它们 
之 间 如 何 互相 注入 的 配置 。 
。 属性 注入 : 设置 Spring 应 用 上 下 文中 bean 的 值 的 配置 。 


在 Spring 的 XML 方式 和 基于 Java 的 配置 中 ， 这 两 种 关 型 的 配置 通 痢 
会 在 同一 个 地 方 显 式 声 明 。 在 其 于 Java 的 配置 中 ， 和 市 有 @Bean 注 解 的 方 
法 一 般 会 同时 初始 化 bean 并 立即 为 它 的 属性 设置 值 。 例 如 ， 请 查看 下 面 
这 个 市 有 @Bean 注 解 的 方法 ， 它 会 为 艇 入 式 的 H2 数 据 库 声 明 一 个 


DataSource: 


QBean 
public DataSource dataSource() { 
return new EmbeddedDataSourceBuilder() 
.SetType(H2) 
.addScript("taco schema.sql") 
.addScripts("user data.sql", "ingredient data.sql") 
.build(); 





在 这 里 ，addScript() 和 addScripts0 方 法 设置 了 一 些 String 类 型 的 属 
性 ， 它 们 是 在 数据 源 束 绊 之 后 要 用 到 数据 库 上 的 SQL 脚 本 。 这 束 古 不 使 
用 Spring Boot 时 我 们 配置 DataSource bean 的 方法 ， 但 是 借助 自动 配置 的 
功能 ， 碌 完全 没有 必要 使 用 这 种 方法 了 。 


如 果 在 运行 时 类 路 径 中 能 够 找到 H2 依 赖 ， 那 么 Spring Boot 会 自动 在 
Spring 应 用 上 下 文中 创建 对 应 的 DataSource bean。 这 个 bean 会 运行 名 为 
schema.sql 和 data.sql 的 脚本 。 


但 是 ， 如 末 我 们 想 要 给 SQL 脚本 使 用 其 他 的 名 称 ， 议 怎么 办 呢 ? 或 
者 ， 如 末 我 们 想 要 指定 两 个 以 上 的 SQL 脚本 又 该 怎么 谷 呢 ? 这 束 是 配置 
属性 能 够 友 挥 作用 的 地 方 了 。 但 是 ， 在 开始 使 用 配置 属性 之 前 ， 我 们 需 
要 理解 这 些 属性 是 从 哪里 来 的 。 


5.1.1 理解 Spring 的 环境 抽象 
Spring 的 环境 抽象 是 各 种 配置 属性 的 一 站 式 服 务 。 它 抽取 了 原始 的 


属性 ， 这 样 需 要 这 些 属 性 的 bean 束 可 以 从 Spring 本 里 中 获取 了 。Spring 
环境 会 拉 取 多 个 属性 源 ， 包 括 : 


。JVM 系 统 属性 ; 
。 操作 系统 环境 变量 ; 
。 命令 行 参数 ; 
。 应 用 属性 配置 文件 。 
它 会 将 这 些 属 性 聚合 到 一 个 源 中 ， 通 过 这 个 源 可 以 注入 到 Spring 的 
bean 中 。 图 5.1 前 述 了 来 目 各 个 属性 源 的 属性 是 如 何 流 经 Spring 的 环境 抽 
象 进 入 Spring bean 的 。 
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图 5.1 Spring 环境 从 各 个 属性 源 拉 取 属 性 ， 并 让 Spring 应 用 上 下 文中 的 bean 可 以 使 用 它们 


Spring Boot 目 动 配置 的 bean 都 可 以 通过 Spring 环境 提取 的 属性 进行 
配置 。 举 个 人 简单 的 例子 ， 假 设 我 们 希望 应 用 搬 层 的 Servlet 容 右 使 用 为 外 
一 个 只 口 监 听 请 求 ， 而 不 再 使 用 8080。 为 了 实现 这 一 点 ， 我 们 可 以 
在 “src/main/resources/application.properties” 中 将 server.port 设 置 成 一 个 不 


同 的 珊 口 ， 如 下 所 示 : 


| server .port=9698 | 
在 设置 属性 的 时 候 ， 我 个 人 更 喜欢 使 用 YAML。 所 以 ， 我 通常 不 会 


使 用 application.properties， 而 是 在 “src/main/resources/application.yml” 中 


设置 server.port 的 值 ， 如 下 所 示 : 


如 果 你 到 欢 在 外 部 配置 该 属性 ， 那 么 可 以 在 使 用 命令 行 参数 局 动 应 
用 的 时 候 指 定 病 口 : 





$ java -jar tacocloud-6.6.5-SNAPSHOT.Jjar --server.port=9690 


如 果 你 布 望 应 用 始终 在 一 个 特定 的 端口 局 动 ， 那 么 可 以 通过 操作 系 
统 的 环境 变量 进行 一 次 性 的 设置 : 


$ export SERVER_PORT=9696 


需要 注意 ， 在 将 属性 设置 为 环境 变量 的 时 候 ， 命 名 风格 略 有 不 同 ， 
这 样 做 是 为 了 适应 操作 系统 对 环境 变量 名 称 的 限制 。 不 过 ， 没 有 关系 ， 
Spring 能 够 将 其 挑选 出 来 ， 并 将 SERVER_PORT 解 析 为 server.port。 


正如 我 前 和 面 所 说 ， 有 多 种 配置 属性 的 方法 。 当 我 们 学 习 第 14 章 的 时 
修 ， 你 会 看 到 为 外 一 种 设置 属性 的 方法 ， 那 束 古 通过 中 心 化 的 配置 服务 
俐 实现 。 实 际 上 ， 我 们 可 以 使 用 几 百 个 配置 属性 来 调整 Spring bean 的 行 
为 。 你 已 经 看 到 了 其 中 的 一 部 分 ， 比 如 本 章 中 已 经 介绍 的 server.port。 


在 本 章 中 ， 我 们 不 可 能 介绍 所 有 可 用 的 配置 属性 。 尽 过 如 此 ， 我 们 


还 是 可 以 了 解 一 些 你 可 能 会 经 党 过 到 的 非 第 有 用 的 配置 属性 。 我 们 上 有 先 
看 一 下 能 够 调整 自动 配置 的 数据 产 的 一 些 属性 。 


5.1.2 ”配置 数据 源 


此 时 ，Taco Cloud 应 用 疝 未 完成 ， 在 该 应 用 准备 部 彰 之 前 ， 我 们 还 
有 好 几 个 章节 来 完善 它 。 因 此 ， 使 用 骸 入 式 的 H2 数 据 库 作为 数据 源 非 
音 适 合 我 们 的 种 求 ， 人 至 少 束 目前 来 看 是 这 样 的 。 但 是 ， 一 旦 要 将 应 用 部 
普 到 生产 环境 中 ， 你 可 能 需要 考虑 一 个 更 加 持久 的 数据 库 解 决 方案 。 


尽管 我 们 可 以 显 式 地 配置 自己 的 DataSource， 但 通常 没有 必要 这 样 
人 做。 相反， 通过 配置 属性 设置 数据 库 URL 和 和 凭证 信息 会 更 加 简单 。 例 
如 ， 如 过 你 想 要 开始 使 用 MySQL 数 据 库 ， 那 么 可 以 把 如 下 的 配置 属性 
还 加 到 application.yml 中 : 


Spring : 
datasource: 


url: JjJdbc:mysql://l1ocalhost/tacocloud 
username: tacodb 
password: tacopassword 





尽管 我 们 需要 将 对 应 的 JDBC 驱 动 添加 到 构建 文件 中 ， 但 是 我 们 不 
需要 指定 JDBC 驱 动 类 。Spring Boot 会 根据 数据 库 URL 的 结构 推算 出 
来 。 然 和 而， 如 果 这 样 做 有 问题 的 话 ， 我 们 依然 可 以 通过 


spring.datasource.driver-class-name 必 性 来 进行 设置 : 





spring: 
datasource: 
url: JjJdbc:mysql://l1ocalhost/tacocloud 


Username: tacodb 
password: tacopassword 
driver-class-name: com.mysql.Jjdbc.Driver 





Spring Boot 在 自动 化 配置 DataSource bean 的 时 候 ， 会 使 用 该 连接 。 
如 果 在 类 路 径 中 存在 Tomcat 的 JDBC 连 接 池 ，DataSource 将 使 用 该 连 接 
池 。 人 否则 ，Spring Boot 将 会 在 类 路 低下 尝试 查找 并 使 用 如 下 的 连接 池 实 
了 : 


e HikariCP 
e Commons DBCP 2 


目 动 配置 所 能 支持 的 连接 池 可 选 方案 仪 有 这 些 ， 但 是 随时 欢迎 显 式 
配置 DataSource bean， 这 样 你 可 以 使 用 任意 喜欢 的 连接 池 实 现 。 
在 本 和 草 前 面 的 内 容 中 ， 我 们 建议 要 有 一 种 方式 声明 应 用 局 动 的 时 候 


要 执行 的 数据 库 初 始 化 脚本 。 在 这 种 情况 下 ，spring.datasource.schema 
和 spring.datasource.data 属 性 束 非 常 有 用 了 : 


spring: 
datasource: 
schema: 
- order-schema.sql 


- ingredient-schema.sql 
- taco-schema.sql 

- User-schema.sql 

data: 

- ingredients.sql 





有 有 的 读者 可 能 无 法 使 用 显 式 配置 数据 源 的 方式 ， 而 是 更 加 倾 回 于 在 
JNDI 中 配置 数据 产 并 让 Spring 去 那里 进行 租 找 。 在 这 种 情况 下 ， 我 们 可 
以 使 用 spring.datasource.jndi-name 搭 建 目 己 的 数据 源 : 


Spring : 
datasource: 


JnNndi-name: java:/comp/env/jdbc/tacoCloudDS 





如 果 我 们 设置 了 spring.datasource.jndi-name 属 性 ， 其 他 的 数据 库 连 
接 属 性 (已经 设置 了 了 的话) 融会 修 急 上 略 挥 。 


5.1.3 ”配置 先入 式 服务 鼎 


我 们 已 经 看 到 过 如 何 使 用 server.port 属 性 来 配置 servlet 容 器 的 端口 。 
但 是 ， 我 还 没有 展示 将 server.port 设 置 为 0 将 会 出 现 什 么 状况 : 


尽管 我 们 将 server.port 属 性 显 式 设置 成 了 0， 但 是 服务 器 并 不 会 真 的 
在 端口 0 上 局 动 。 相 反 ， 它 会 任 选 一 个 可 用 的 端口 。 在 我 们 运行 目 动 化 
集成 测试 的 时 低 ， 这 会 非常 有 用 ， 因 为 这 样 能 够 你 证 并 友 运 行 的 测试 不 
会 与 便 编码 的 端口 写 冲 突 。 在 第 13 章 中 我 们 将 会 看 到 ， 如 果 不 关 心 应 
用 在 哪个 亲口 局 动 ， 那 么 这 种 配置 方 式 也 非 党 有 用 ， 因 为 此 时 应 用 将 会 
变 成 通过 服务 注册 中 心 来 进行 查找 的 微服 务 。 


但 是 ， 搬 层 服务 器 的 配置 并 不 仅仅 局 限于 一 个 病 口 ， 我 们 对 搬 层 容 
器 第 见 的 一 项 设置 束 是 让 它 处 理 HTTPS 请 求 。 为 了 实现 这 一 点 ， 我 们 肯 
先 要 使 用 JDK 的 keytool 命 令 行 工 具 生 成 keystore: 


$ keytool -keystore mykeys.jks -genkey -alias tomcat -keyalg RSA 


在 这 个 过 程 中 ， 会 询问 我 们 一 些 关 于 名 称 和 组 织 机 构 相 关 的 问题 ， 
大 多 数 问 题 部 无 天 案 要 。 但 是 ， 它 拓 示 输入 密码 的 时 候 裔 要 记 住 你 所 选 
择 有 的 密码 。 在 本 例 中 ， 我 选择 使 用 letmein 作 为 密码 。 


接 下 来 ,我们 需要 设置 一 些 属性 ， 以 便于 在 艇 入 式 服 务 占 中 局 用 
HTTPS。 我 们 可 以 在 命令 行 中 进行 配置 ， 但 是 这 种 方式 非常 不 方便 ， 相 
反 ， 你 可 能 更 愿意 通过 application.properties 或 application.yml 文 件 来 声明 
配置 。 在 application.yml 中 ， 配 置 属性 如 下 所 示 : 


port: 8443 
ssl: 


key-store: file:///path/to/mykeys.jJks 
key-store-password: letmein 
Key-password: letmein 





在 这 里 ， 我 们 将 server.port 设 置 为 8443， 这 是 在 开发 阶段 HTTPS 服 
务 右 的 单 用 选择 。server.ssl.key-store 属 性 应 该 设置 为 我 们 所 创建 的 
keystore 文 件 的 跤 人 笃 。 在 这 里 ， 它 使 用 了 file:// URL， 因 此 会 在 文件 系统 
中 加 载 ， 但 是 ， 如 果 你 需要 将 它 打 包 到 一 个 应 用 JAR 文 件 中 ， 束 需要 使 
用 “classpath:”URL 来 引用 它 。server.ssl.key-store-password 和 和 
server.Ssl.key-password 属 性 都 设置 成 了 创建 keystore 时 所 设置 的 密 位 。 


这 些 属性 准备 束 绪 之 后 ， 应 用 就 会 监听 8443 病 口上 的 HTTPS 请 求 。 
因为 浏览 占 之 间 有 所 差异 ， 所 以 你 可 能 会 迪 到 服务 器 无 法 验证 其 号 份 的 
鱼 告 。 在 开发 阶段 ， 通 过 localhost 提 供 服 务 时 ， 这 其 实 无 纳 担心 。 


5.1.4 ”配置 日 志 


大 多 数 的 应 用 部 会 提供 菏 种 形式 的 日 志 。 即 便 你 的 应 用 本 里 不 下 接 
打印 任何 日 忘 ， 应 用 所 使 用 的 库 肯 定 也 会 以 日 记 的 形式 记录 它们 有 的 活 
动 。 


驮 认 情 况 下 ，Spring Boot 通 过 Logback 配 置 日 志 ， 日 志 会 以 INFO 级 
别 写 入 到 控制 人 台中。 在 运行 应 用 或 其 他 样 例 的 时 候 ， 你 可 能 已 经 在 应 用 
日 志 中 发 现 了 大 量 的 INFO 级 别 的 条 目 


为 了 完全 控制 日 志 的 配置 ， 我 们 可 以 在 类 路 入 的 根 目 录 下 在 
src/main/resources 中 ) 创建 一 个 logback.xml 文 件 。 如 下 是 一 个 简单 
logback.xml 文 件 的 样 例 : 

<configuration> 


<appender name="STDOUT"” class="ch.qos.logback.core.ConsoleAppender"> 
<encoder> 


<pattern> 
%d{HH:mm:ss.SSS} [%thread| %-S5level %logger{36} - %msg%n 
</pattern> 


</encoder> 
</appender> 
<logger name= root ”Jeve1L= INFO /> 
<root level="INFO"> 
<appender-ref ref= STDOUT /> 
</root> 
</configuration> 





除了 日 志 所 使 用 的 模式 之 外 ， 这 个 Logback 配 置 和 没有 logback.xml 
文件 时 的 默认 行为 几乎 是 相同 的 。 但 是 ， 通 过 编辑 logback.xml 文 件 ， 我 
们 可 以 完全 控制 应 用 的 日 六 文件 。 


注意 : 天 于 logback.xml 文 件 中 都 可 以 声明 哪些 内 容 ， 这 超出 





了 本 书 的 范围 。 你 可 以 参考 Logback 的 文档 来 了 解 更 多 信息 。 





在 日 志 配 置 方面 ， 你 可 能 遇 到 的 冲 见 变更 束 是 修改 日 志 级 唱和 指定 
日 志 写 入 到 哪个 文件 中 。 借 助 Spring Boot 的 配置 属性 功能 ， 我 们 不 用 创 
建 logback.xml 文 件 束 能 完成 这 些 变 更 。 


要 设置 日 志 级 出， 我 们 可 以 创建 以 logging.level 作 为 前 级 的 属性 ， 
随后 案 跟 看 的 是 我 们 想 要 设置 日 志 级 别 的 logger。 假 设 ， 我 们 想 要 将 root 
logging 设 置 为 WARN 级 别 ， 但 是 希望 将 Spring Security 的 日 志 级 别 设置 
为 DEBUG。 那 么 ， 在 application.yml 中 添加 如 下 的 条 目 就 能 实现 我 们 的 


水: 


Jogglng: 
level: 
root: WARN 


org: 
springframework: 
security: DEBUG 





我 们 还 可 以 将 Spring Security 的 包 名 局 平 化 到 一 行 中 ， 使 其 更 易于 
洁 读 : 


logging: 
level: 


root: WARN 
org.springframework.security: DEBUG 





现在 ， 假 设 我 们 想 要 将 日 志 条 目 写 入 到 “/var/logs/”* 中 的 
TacoCloud.log 文 件 中 。logging.path 和 logging.file 文 件 可 以 按照 如 下 形式 


进行 设 症 : 


logging: 
path: /var/logs/ 
file: TacoCloud .1Log 
level: 


root: WARN 
org: 
springframework: 
security: DEBUG 





假设 应 用 有 具 有“/var/logs/”? 目 好 的 写 入 权限 ， 那 么 日 志和 条 目 会 写 入 
到 “/var/logs/ TacoCloud.log” 文 件 中 ， 默 认 情 况 下 ， 日 志文 件 一 旦 达到 
10MB， 就 会 轮换 。 


5.1.5 ”使 用 特定 的 属性 人 
在 设置 属性 的 时 候 ， 我 们 并 非 必须 要 将 它们 的 值 设置 为 硬 编码 的 
String 或 数值 。 其 实 ， 我 们 还 可 以 从 其 他 的 配置 属性 派生 值 。 


例如 ， 假 设 《〈 不 管 基于 什么 原因 ) 我 们 想 要 设置 一 个 名 为 
greeting.welcome 的 属性 ， 它 的 值 来 源 于 名 为 spring.application.name 的 男 
一 个 属性 。 为 了 实现 该 功能 ， 在 设置 greeting.welcome 的 时 候 ， 我 们 可 以 
使 用 ${} 占 位 符 标 记 : 


greeting: 
welcome: ${spring.application.name} 


我 们 长 至 可 以 将 占 位 符 能 入 到 其 他 文本 中 : 


areetine: | 


| welcome: You are using ${spring.application.name}. | 


我 们 可 以 看 到 ， 在 配置 Spring 目 己 的 组 件 时 ， 使 用 配置 属性 可 以 很 
容 多 地 将 人 注入 这 些 组 件 属 性 中 ， 并 且 可 以 细 料 度 地 调整 目 动 配置 功 
能 。 配 置 属性 并 不 专属 于 Spring 创 建 的 bean。 我 们 稍微 下 点 功夫 束 可 以 
在 自己 的 bean 中 使 用 配置 属性 功能 。 接 下 来 ， 让 我 们 看 一 下 如 何 实现 。 


5.2 ”创建 自己 的 配置 属性 


正如 我 在 前 文 所 述 ， 配 置 属性 只 不 过 是 bean 的 属性 ， 它 们 可 以 从 
Spring 的 环境 抽象 中 接 党 配置 。 我 还 没有 提 及 的 是 这 些 bean 访 如何 消 费 
这 些 配置 。 


为 了 文 持 配置 属性 的 注入 ，Spring Boot 提 供 了 
(@ConfigurationProperties 注 解 。 将 它 放 到 Spring bean 上 之 后 ， 它 束 会 为 
该 bean 中 那些 能 够 根据 Spring 环境 注入 值 的 属性 赋值 。 


为 了 阐述 @ConfigurationProperties 是 如 何 运 行 的 ， 假 设 我 们 为 


OrderControlleri 寺 加 了 如 下 的 方法 ， 谤 方法 会 列 出 当前 认证 用 户 过 去 的 
订单 : 


Q@GetMapping 
public String ordersForUser( 
@QAuthenticationpPrincipal User user, Model model) { 


model.addAttribute("orders", 
orderRepo.findByUserOrderByPlacedAtDesc(user)); 


return "orderList"; 


} 





除 此 之 外 ， 我 们 还 要 为 OrderRepository 添 加 必要 的 findByUserO) 方 
法 : 


List<Order> findByUserOrderByPlacedAtDesc(User User ) ; 


注意 ， 这 个 repository 方 法 使 用 了 OrderByPlacedAtDesc 子 人 句 。 
OrderBy 区 域 指定 了 结果 要 按照 什么 属性 来 排 订 ， 在 本 例 中 ， 也 就 古 
placedAt 必 性。 最 后 的 Desc 声 明 要 鬼 照 降序 进行 排列 。 所 以 ， 返 回 的 订 
早 将 会 按照 时 间 由 近 及 远 进 行 排 厅 。 


按照 这 种 写法 ， 如 果 用 户 只 创建 了 少量 订单 ， 那 么 这 个 控制 右 方 法 
可 能 会 非 党 有用， 但是， 对 于 狂热 的 taco 爱 好 者 来 说 ， 这 种 方式 束 显 得 
有 些 不 方便 了 。 在 浏览 器 中 显示 一 些 订单 会 很 有 用 ， 但 是 一 长 串 没完 没 
了 的 订单 列表 简直 束 是 “噪声 ”。 假 设 ， 我 们 希望 将 显示 的 订单 数量 限制 
为 最 近 的 20 个 ， 那 么 我 们 可 以 按照 如 下 方式 来 修改 ordersForUser(): 


Q@QGetMapping 
public String ordersForUser( 
OAuthenticationPrincipal User user, Model model) { 


Pageable pageable = PageRequest.of(6@, 20); 
model.addAttribute("orders", 
orderRepo.findByUserOrderByPlacedAtDesc(user, pageable)); 


return “orderList"; 


} 





OrderRepository 也 需要 对 应 修改 : 


List<Order> findByUserOrderByPlacedAtDesc( 
User user, Pageable pageable); 


现在 ， 我 们 修改 了 findByUserOrderByPlacedAtDesc() 方 法 的 签名 ， 
使 其 能 够 接受 Pageable 参 数 。Pageable 是 Spring Data 根 据 页 号 和 每 页 数量 
选取 结果 的 子 集 的 一 种 方法 。 在 ordersForUser() 控 制 器 方法 中 ， 我 们 构 
建 了 一 个 PageRequest 对 象 ， 访 对 象 实现 了 Pageable， 我 们 将 其 声明 为 请 
求 第 一 页 〈 序 号 为 0) 的 数据 ， 并 且 每 页 数量 为 20， 这 样 我 们 束 能 获取 
当前 用 户 最 近 的 20 个 订单 。 


尽 赎 这 种 方式 能 够 很 好 地 运行 ， 但 是 我 们 在 这 里 便 编 僻 了 每 页 的 数 
量 ， 这 有 所 让 人 担心 。 如 有 果 我 们 以 后 友 现 展示 20 个 订 蛙 太 多 ， 并 决定 将 
其 修改 为 10 个 ， 那 该 怎么 办 ? 因为 这 个 值 是 便 编 码 的 ， 所 以 需要 重新 构 
建 和 重新 部 闭 应 用 。 

我 们 可 以 将 每 页 数量 设置 成 一 个 日 定义 的 配置 属性 ， 而 不 是 价 编 码 
到 代码 中 。 首 先 ， 我 们 二 要 江 加 一 个 名 为 pageSize 的 新 属性 到 
OrderController 中 ， 并 为 OrderController 水 加 @ConfigurationProperties 注 
解 ， 如 程序 清单 5.1 所 示 。 


程序 清单 5.1 在 OrderController 中 局 用 配置 属性 功能 





@Controller 

@QRequestMapping("/orders") 
QSessionAttributes("order") 
@ConfigurationpProperties(prefix="taco.orders") 
public class OrderController { 


private int pageSize = 20; 


public void setPpageSize(int pageSize) { 
this.pageSize = pageSize,; 


} 


Q@QGetMapping 
public String ordersForUser( 
OAuthenticationPrincipal User user, Model model) { 


Pageable pageable = PageRequest.of(68, pageSize); 
model.addAttribute("orders", 

orderRepo.findByUserOrderByPlacedAtDesc(user, pageable)); 
return “orderList"; 


} 





程序 清单 5.1 最 重要 的 变更 是 添加 了 Q@ConfigurationProperties 注 解 。 
它 的 prefix 属 性 说 置 成 了 taco.orders， 这 意味 看 当 设 置 pageSize 的 时 候 ， 
我 们 需要 使 用 名 为 taco.orders.pageSize 的 配置 属性 。 


新 的 pageSize 值 默认 为 20， 但 是 通过 设置 taco.orders.pageSize 属 性 ， 
我 们 可 以 很 容易 地 将 其 修改 为 任意 的 值 。 例 如 ， 我 们 可 以 在 
application.yml 中 按照 如 下 的 方式 设置 该 属性 : 
taco: 


orders: 
pageSize: 106 


如 果 在 生产 环境 中 需要 快速 更 改 ， 我 们 可 以 将 taco.orders.pageSize 
设置 为 环境 变量 ， 这 样 焉 不 用 重新 构建 和 重新 部 普 应 用 了 : 


$ export TACO ORDERS PAGESIZE=106 


设置 配置 属性 的 任何 方式 都 可 以 用 来 调整 最 近 订单 页 面 中 每 页 的 数 
量 。 接 下 来 ， 我 们 看 一 下 如 何在 属性 持 有 者 〈property holder) 中 设置 配 
置 数 据 。 


5.2.1 和 定义 配置 属性 的 持 有 者 


这 里 并 没有 说 @ConfigurationProperties 只 能 用 到 控制 器 或 特定 类 型 
的 bean 中 。@ConfigurationProperties 实 际 上 通常 会 放 到 一 种 特定 类 型 的 
bean 中 ， 这 种 bean 的 目的 束 是 持 有 配置 数据 。 这 样 的 话 ， 特 定 的 配置 细 
市 束 能 从 控制 颖 和 其 他 应 用 程序 类 中 抽 离 出 来 ， 多 个 bean 也 能 更 容易 地 
共 圣 一 些 通 用 的 配置 。 


针对 OrderController 中 的 pageSize 属 性 ， 我 们 可 以 将 其 抽取 到 一 个 单 
独 的 类 中 。 程 序 清单 5.2 束 以 这 样 的 方式 来 使 用 OrderProps 类 。 


程序 清单 5.2 ”将 pageSize 抽 取 到 持 有 者 类 中 


package tacos.web,; 
import org.sprIngframework.boot .context .propertiles . 


ConfigurationProperties; 
import org.springframework.stereotype.Component; 
import lombok.Data; 


QComponent 


@ConfigurationpProperties(prefix="taco.orders") 
@Data 


public class OrderProps { 


private int pageSize = 20; 





束 像 我 们 在 OrderController 中 所 做 的 那样 ，pageSize 的 默认 值 为 20， 
OrderProps 使 用 了 @ConfigurationProperties 注 解 并 且 将 前 级 设置 成 了 
taco.orders。 这 个 类 还 用 到 了 @Component 注 解 ， 这 样 Spring 的 组 件 扫描 
功能 会 自动 发 现 它 并 将 其 创建 为 Spring 应 用 上 下 文中 的 bean。 这 是 非常 


重要 的 ， 因 为 我 们 下 一 步 要 将 OrderProps 作 为 bean 注 入 到 OrderController 
中 。 


配置 属性 持 有 者 并 没有 什么 特别 之 处 。 它 们 只 是 将 Spring 环境 注入 
到 其 属性 中 的 bean。 它 们 可 以 注入 到 任意 需要 这 些 属性 的 其 他 bean 中 。 
对 于 OrderController 来 说 ， 我 们 束 可 以 从 OrderController 中 移 除 
pageSize， 并 注入 和 使 用 OrderProps bean: 


@Controller 
@QRequestMapping("/orders") 
QSessionAttributes("order") 
public class OrderController { 


private OrderRepository orderRepo ; 
private OrderProps props; 


public OrderController(OrderRepository orderRepo, 
orderProps props) { 
this.orderRepo = orderRepo ; 
this.props = props; 


} 


Q@GetMapping 
public String ordersForUser( 
@QAuthenticationpPrincipal User user, Model model) { 


Pageable pageable = PageRequest.of(6，props.getPageSize() ) ; 
model.addAttribute("orders", 
orderRepo.findByUserOrderByPlacedAtDesc(user, pageable)); 


return "orderList"; 


} 





现在 ，OrderController 不 需要 负责 处 理 自 己 的 配置 属性 了 。 这 样 能 
够 让 OrderController 中 的 代码 更 加 整洁 一 些 ， 并 且 能 够 让 其 他 的 bean 午 
用 OrderProps 中 的 属性 。 除 此 之 外 ， 我 们 可 以 将 订单 相关 的 属性 全 部 了 放 
到 一 个 地 方 ， 也 吏 是 OrderProps 关 中 。 如 末 我 们 需要 讨 如 、 删 除 、 重 命 
名 或 者 以 其 他 方式 更 改 其 中 的 属性 ， 我 们 只 需要 在 OrderProps 中 进行 变 
更 束 可 以 了 。 


例如 ， 假 设 我 们 在 多 个 其 他 的 bean 中 也 用 到 了 pageSize 属 性 ， 现 在 
我 们 决定 要 对 这 个 属性 的 值 进行 一 些 校 验 ， 限 制 它 的 值 必须 要 不 小 于 5 
且 不 大 于 25。 如 果 没 有 持 有 者 bean， 我 们 必须 要 将 校 验 注 解 用 到 
OrderController 的 pageSize 属 性 上 以 及 其 他 所 有 使 用 该 属性 的 类 上 。 但 
是 ， 因 为 我 们 现在 将 pageSize 抽 取 到 了 OrderProps 中 ， 所 以 只 需要 修改 
OrderProps 束 可 以 了 了: 


package tacos.web; 
Import javax.validation.constraints.Max; 
Import javax.validation.constraints.Min; 


import org.springframework.boot.context.properties. 
ConfigurationProperties; 

Import org.springframework.stereotype.Component,; 

import org.springframework.validation.annotation.Validated; 


import lombok.Data; 


QComponent 
@ConfigurationPproperties(prefix="taco.orders") 
@Data 

@Validated 

public class OrderProps { 


QMin(value=5, message="must be between 5 and 25") 
@QMax(value=25, message="must be between 5 and 25") 
private int pageSize = 20; 


} 
//end: :validated | ] 


尽管 我 们 很 容易 束 可 以 将 @Vvalidated、@Q@Min 和 @Max 注 解 用 到 
OrderController《 和 其 他 可 以 注入 OrderProps 的 地 方 )， 但 是 这 样 会 使 
OrderController 更 加 混乱 。 通 过 配置 属性 的 持 有 者 bean， 我 们 将 所 有 的 
配置 属性 收集 到 了 一 个 地 方 ， 这 样 束 能 让 使 用 这 些 属性 的 bean 尺 可 能 你 


持 整 洁 。 


5.2.2 ”声明 配置 属性 元 数据 


在 IDE 中 ， 你 可 能 会 发 现 application.yml (或 application.properties) 
文件 的 taco.orders. pageSize 条 目 上 会 有 一 条 警告 信息 ， 根 据 IDE 不 同 显 示 
会 有 所 差异 ， 这 个 警 香 提示 的 内 容 可 能 是 “Unknown property ‘taco””。 这 
个 葡 告 产生 的 原因 在 于 我 们 刚刚 创建 的 配置 属性 缺少 元 数据 。 图 5.2 展 
示 了 在 Spring Tool Suite 中 ， 当 我 将 鼠标 巧 停 到 taco 属 性 时 的 样式 。 


W%10 ‘Unknown property 'taco' 
orders: 
page-slize: 10 


图 5.2 ”缺少 配置 属性 元 数据 所 产生 的 警告 


配置 属性 的 元 数据 完全 是 可 选 的 ， 它 并 不 会 妨碍 配置 属性 的 运行 。 
但 是 ， 元 数据 对 于 为 配置 属性 提供 一 个 最 小 化 的 文档 非常 有 用 ， 在 IDE 
中 尤为 如 此 。 


举例 来 说 ， 将 鼠标 指针 悬 停 到 security.user.password 属 性 上 时 ， 就 会 
看 到 图 5.3 那 样 的 效果 。 尽 管 优 俘 对 我 们 的 帮助 很 有 限 ， 但 是 它 足 以 让 
我 们 知道 这 个 属性 是 做 什么 的 以 及 如 何 使 用 它 。 


| security: 
User: 
name: buzz 
password: infinity 


security.user.password 
% taco9 java.lang.String 


OF Password for the default user name. 
wy Co2s 
x MaN dssmerrs 而 


图 5.3” Spring Tool Suite 中 配置 属性 的 基 停 文档 


为 了 帮助 那些 使 用 你 所 定义 的 配 普 属性 的 人 (有 可 能 就 是 你 本 
人 ) ， 为 这 些 属性 创建 一 些 元 数据 是 非常 好 的 办 法 ， 至 少 它 能 消除 IDE 
上 那些 烦人 的 黄色 警告 。 


为 了 创建 目 定 义 配 置 属性 的 元 数据 ， 我 们 需要 在 META-INF 下 创建 
一 个 名 为 additional-spring-configuration-metadata.json 的 文件 (比如 ， 在 
项 目的 “src/main/resources/ META-INF” 目 录 下 ) 。 


快速 添加 缺失 的 元 数据 


如 果 使 用 Spring Tool Suite， 残 会 有 一 个 创建 缺失 属性 元 数据 的 快速 
修正 选项 。 将 鼠标 放 到 缺失 元 数据 敬告 的 那 行 代码 上 ， 在 Mac 下 按 
CMD+1 组 合 键 或 者 在 Windows 和 Linux 下 按 Ctrl+1 组 合 键 束 能 打开 快速 修 
下 的 弹出 框 ( 见 图 5.4)〉。 


邮 bacso: 
了 Create metadata for 'taco.orders.page-Size' Add property 'taco.orders.page-size' to the 'additional- 
spring-configuration-metadata.json' file in project 


x| 0 opert t. 
lgnore "Unknown property in projec 'ch05_taco-cloud' 


X| Ilgnore 'Unknown property' in workspace. 


10 ma 


Press 'Tab' from proposal table or click for focus 


图 5.4 在 Spring Tool Suite 中 通过 快速 修正 弹出 框 创建 配置 属性 





人 然后， 选择 “Create Metadata for ...” 选 项 来 为 属性 添加 元 数据 (会 在 
additional-spring- configuration-metadata.json 文 件 中 进行 添加 ) ， 如 果 文 
件 还 不 存在， 将 会 目 动 创建 该 文件 。 


对 于 taco.orders.pageSize 属 性 来 说 ， 我 们 可 以 通过 如 下 的 JSON 为 其 
洪 加 元 数据 : 


{ 


"properties": | 
{ 
“name : “taco.orders.page-SlIze ， 
"type": "Java.lang.String", 


"description": 
"Sets the maximum number of orders to display in a list." 





需要 注意 ， 在 元 数据 中 引用 的 属性 名 为 taco.orders.page-size。 Spring 
Boot 灵 活 的 属性 命名 功能 允许 属性 名 出 现 不 同 的 变种 ， 比 如 


taco.orders.page-size 等 价 于 taco.orders.pageSize。 


元 数据 准备 融 绪 之 后 ， 和 警告 信 息 驶 会 消失 了 。 除 此 之 外 ， 如 琳 将 鼠 


标 指针 巧 停 到 taco.orders. pageSize 属 性 上 ， 惑 会 看 到 如 网 5.5 所 示 的 摘 述 
兰 园 


吴 4DA oO 


6 taco: 
orders: 
pageSize: 10 


taco.orders.page-size 
java.lang.String 


Sets the maximum number of orders to display in a list. 


图 5.5 目 定 义 配 置 属性 的 惹 俘 玫 助 信息 


为 外 ， 在 IDE 中 ， 束 像 Spring 本 里 提供 的 配置 属性 一 样 ， 我 们 还 能 
具备 目 动 补 全 功能 ， 如 图 5.6 所 示 。 


10 tacol| 


taco.orders.page-size : String taco.orders.page-size 


spring.mustache.content-type : org.springframework.util.MimeType java.lang.String 
spring.data.couchbase.auto-index : boolean 有 | 
= spring.data.couchbase.consistency : org.springframework.data.cou Sets the maximum number of orders to display in a list. 
四 14 spring.jta.narayana.one-phase-commit : boolean 
spring.jta.narayana.recovery-db-pass : String 
spring.jta.narayana.recovery-db-user : String 


SFIS Edo see FAVA APS ies Wares = C#rines 


图 5.6 ”配置 属性 的 元 数据 能 够 帮助 实现 属性 的 目 动 补 全 功能 


我 们 可 以 看 到 ， 配 置 属性 对 于 调整 自动 配置 的 组 件 以 及 应 用 程序 自 
丑 的 pean 都 非常 有 用 。 但 是 ， 如 末 我 们 想 要 为 不 同 的 部 阔 环境 配置 不 同 
的 属性 又 该 怎么 办 呢 ? 接 下 来 ， 我 们 看 一 下 该 如 何 使 用 Spring profile 搭 
建 特定 环境 的 配置 。 


5.3 ”使 用 profile 进 行 配置 


当 应 用 部 车 到 不 同 的 运行 时 坏 境 中 的 时 候 ， 有 些 配 置 细节 通常 会 有 
些 才 别 。 例 如 ， 数 据 库 连 接 的 细 市 在 开发 环境 和 质量 你 证 (guality 
assurance) 环境 中 可 能 束 不 相同 ， 而 它们 与 生产 环境 可 能 义 不 一 样 。 配 
置 不 同 环境 之 间 有 天 异 的 属性 时 ， 有 种 办 法 殉 是 使 用 环境 变量 ， 通 过 这 
种 方式 来 指定 配置 属性 ， 而 不 是 在 application.properties 和 application.yml 
中 进行 定义 。 


例如 ， 在 开 肥 阶段 ， 我 们 可 以 依赖 目 动 配置 的 能 入 却 H2 数 据 库 。 
但 征 在 生产 环境 中 ， 我 们 可 以 按照 如 下 的 方式 将 数据 库 配 站 属性 议 症 为 
环境 变量 : 


% export SPRING DATASOURCE URL=jdbc:mysql://localhost/tacocloud 


% export SPRING DATASOURCE USERNAME=tacouser 
% export SPRING DATASOURCE PASSWORD=tacopassword 





尽 官 这 种 方式 可 以 运行 ， 但 是 如 条 配置 属性 比较 多 ， 那 么 将 它们 声 
明 为 环境 变量 会 非 第 抹 烦 。 际 此 之 外 ， 我 们 没有 好 的 方式 来 跟 踩 环境 变 
量 的 变化 ， 也 无 法 在 出 现 错误 的 时 候 进行 回 滚 。 


相对 于 这 种 方式 ， 我 更 加 倾向 于 采用 Spring profile。profile 是 一 种 
条 件 化 的 配置 ， 在 运行 时 ， 根 据 哪 些 profile 处 于 激活 状态 ， 可 以 使 用 或 
忽略 不 同 的 bean、 配 置 类 和 配置 属性 。 


例如 ， 为 了 开 友 和 调试 方便 ， 我 们 希望 使 用 骸 入 式 的 H2 数 据 库 ， 
并 且 Taco Cloud 代 码 的 日 志 级 别 为 DEBUG。 但 是 在 生产 环境 中 ， 我 们 希 
硼 使 用 外 部 的 MySQL 数 据 库 ， 并 将 日 志 级 列 设 置 为 WARN。 在 开 友 场 
景 下 ， 我 们 可 以 很 容 多 地 放置 数据 源 属 性 并 使 用 目 动 配置 的 H2 数 据 


库 。 对 于 调试 级 别 的 日 六 需求 ， 我 们 可 以 在 application.yml 文 件 中 通过 
logging.level.tacos 属 性 将 tacos 基 础 包 的 日 志 级 别人 设置 为 DEBUG: 
loggineg: 


lJ]evel: 
tacos: DEBUG 


这 束 是 我 们 要 针对 开 友 环境 做 的 事情 。 但 是 ， 如 果 我 们 不 对 
application.yml 做 任何 修改 残 将 应 用 部 着 到 生产 环境 ，tacos 包 依然 会 写 
入 调试 日 专 并 且 依 然 会 使 用 H2 数 据 库 。 我 们 需要 做 的 承 是 定义 一 
profile， 其 中 包含 适用 于 生产 环境 的 属性 。 


5.3.1 定义 特定 profile 的 属性 


定义 特定 profile 相 关 的 属性 的 一 种 方式 束 古 创建 为 外 一 个 YAML 或 
属性 文件 ， 其 中 只 包含 用 于 生产 环境 的 属性 。 文 件 的 名 称 要 如 守 如 下 的 
约定 : application-{fprofile 名 }.yml 或 application-{fprofile 名 }.properties。 然 
后 ， 我 们 束 可 以 在 这 里 再 明 适用 于 该 profile 的 配置 属性 了 。 例 如 ， 我 们 
可 以 创建 一 个 新 的 名 为 application-prod.yml 的 文件 ， 其 中 包含 如 下 属 
性 : 

a 


url: JjJdbc:mysql://l1ocalhost/tacocloud 
username: tacouser 


password: tacopassword 
logging: 
level: 
tacos: WARN 





定义 特定 profile 相 关 的 属性 的 另外 一 种 方式 仅 适 用 于 YAML 配 置 。 
它 会 将 特定 profile 的 属性 和 韭 profile 的 属性 都 放 到 application.yml 中 ， 它 
们 之 间 使 用 3 个 中 划 线 进行 分 割 ， 并 有 旦 使 用 spring.profiles 属 性 来 命名 
profile。 如 采 按 照 这 种 方式 定义 生产 环境 的 属性 ， 等 价 的 application.yml 
如 下 所 未 : 
logging: 


lJ]evel: 
tacos: DEBUG 


spring: 
profiles: prod 


datasource: 
url: JjJdbc:mysql://1localhost/tacocloud 
username: tacouser 
password: tacopassword 


logging: 
lJ]evel: 
tacos: WARN 





我 们 可 以 看 到 ，application.yml 文 件 通 过 一 组 中 划 线 〈---) 分 成 了 
两 部 分 。 第 二 部 分 指定 了 spring.profiles 值 ， 代 表 后 面 的 属性 适用 于 prod 
profile。 而 第 一 部 分 的 属性 没有 指定 spring.profiles， 所 以 它们 是 所 有 
profile 通 用 的 ， 或 者 如 有 果 当 前 激活 的 profile 没 有 设置 这 些 属性 ， 它 们 现 
会 作为 默认 值 。 


不 管 应 用 程序 运行 的 时 候 哪个 profile 处 于 激活 状态 ， 根 据 默 认 
profile，tacos 包 的 日 志 级 别 都 将 会 设置 为 DEBUG。 但 是 ， 如 果 名 为 prod 
的 profile 激 活 ， 那 么 logging.level.tacos 属 性 将 会 被 重 写 为 WARN。 与 之 
类 似 ， 如 采 prod profile 处 于 激活 状态 ， 那 么 数据 源 相 天 的 属性 将 会 被 设 





置 为 使 用 外 部 的 MySQL 数 据 库 。 


通过 创建 模式 为 application-{profile 名 }.yml 或 application-{profile 
名 }.properties 的 YAML 或 属性 文件 ， 我 们 可 以 按 需 定义 任意 数量 的 
profile。 或 者 ， 我 们 也 可 以 在 application.yml 中 再 输入 3 个 中 划 线 ， 结 合 
spring.profiles 属 性 来 指定 其 他 名 称 的 profile， 然 后 深 加 该 profile 特 定 的 相 
天 属性 。 


5.3.2 ”激活 profile 


如 采 我 们 不 激活 这 些 profile， 声 明 profile 相 关 的 属性 其 实 没有 任何 
用 处 。 但 是 ， 我 们 该 如 何 激活 一 个 profile 呢 ? 要 激活 某 个 profile， 需 要 
做 的 束 是 将 profile 名 称 的 列表 赋值 给 spring.profiles.active 必 性。 例如， 在 
application.yml 中 ， 我 们 可 以 这 样 设置 : 

spring: 
profiles: 


active: 
- prod 


但 是 ， 这 可 能 是 激活 profile 最 糟糕 的 一 种 方式 。 如 果 我 们 在 
application.yml 中 设置 处 于 油 活 状态 的 profile， 那 么 这 个 profile 束 会 变 成 
默认 的 profile， 我 们 体验 不 到 使 用 profile 将 生产 环境 相关 属性 和 开发 环 
霹 相 关 的 属性 分 开 的 任何 好 处 。 因 此 ， 我 推荐 使 用 环境 变量 来 设置 处 于 
激活 状态 的 profile。 在 生产 环境 中 ， 我 们 可 以 这 样 设置 
SPRING PROFILES ACTIVE: 


% export SPRING_PROFILES_ACTIVE=prod 


这 样 部 普 到 该 机 器 上 的 任何 应 用 就 都 会 油 活 prod profile， 对 应 的 属 
性 会 比 默 认 profile 具 备 更 高 的 优先 级 。 

如 有 果 以 可 执行 JAR 文 件 的 形式 运行 应 用 ， 那 么 我 们 还 可 以 以 命令 行 
参数 的 形式 放置 激活 的 profile: 





% Java -Jar taco-cloud.Jjar --spring.profiles.active=prod 


你 可 能 已 经 注意 到 了 ，spring.profiles.active 属 性 名 十 复数 形式 的 
profile。 这 意味 看 我 们 可 以 设置 多 个 诉 活 的 profile。 如 末 使 用 环境 变 
量 ， 通 常 这 可 以 通过 过 志 分隔 的 列表 来 实现 : 


但 是 ， 在 YAML 中 ， 我 们 要 按照 如 下 的 方式 米 声 明 列 表 : 


spring: 
profiles: 
active: 


- prod 
- audit 
- ha 





万 外 ， 什 得 一 提 的 是 ， 如 末 我 们 将 Spring 应 用 部 音 到 Cloud Foundry 
中 ， 将 会 目 动 激活 一 个 名 为 cloud 的 profile。 如 果 你 的 生产 环境 是 Cloud 
Foundry， 那 么 你 可 以 将 生产 环境 相关 的 属性 放 到 cloud profile 下。 


在 Spring 应 用 中 ，Pprofile 不 仅 能 够 用 来 条 件 化 地 设置 配置 属性 ， 接 
下 来 我 们 看 一 下 如 何 基 于 处 于 激活 状态 的 profile 来 声明 特定 的 bean。 


5.3.3 ”使 用 profile 条 件 化 地 创建 bean 


有 时候 ， 为 不 同 的 profile 创 建 一 组 独特 的 bean 是 非常 有 用 的 。 正 党 
情况 下 ， 不 管 哪个 profile 处 于 激活 状态 ，Java 配 置 类 中 声明 的 所 有 bean 
都 会 被 创建 。 但 是 ， 假 设 我 们 希望 菜 些 bean 仪 在 特定 profile 激 活 的 情况 
下 才 需 要 创建 。 在 这 种 情况 下 ，@Profile 注 解 可 以 将 某 些 pean 设 置 为 仅 

适用 于 给 定 的 profile。 


例如 ， 在 TacoCloudApplication 中 ， 我 们 有 一 个 CommandLineRunner 
bean， i a 对 村 开 
发 阶段 来 讲 ， 这 是 很 不 错 的 ; 但 是 对 于 生产 环境 的 应 用 来 说 ， 束 没有 必 
要 《也 是 不 符合 需求 的 ) 了 。 为 了 防止 在 生产 部 普 环 境 中 每 次 都 加 载 配 
料 数 据 ， 我 们 可 以 为 声明 CommandLineRunner bean 的 方法 深 加 @Profile 
注解 ， 如 下 所 示 : 


QBean 
@Profile("dev") 
public CommandLineRunner dataLoader(IngredientRepository repo, 


UserRepository userRepo, PasswordEncoder encoder) { 





或 者 ， 假 设 我 们 在 dev 或 qa profile 激 活 的 时 候 都 需要 创建 
CommandLineRunner。 在 这 种 情况 下 ， 我 们 可 以 为 要 创建 的 bean 把 所 有 
profile 都 列 出 来 : 


QBean 
@Profile({"dev", "qa"}) 


public CommandLineRunner dataLoader(IngredientRepository repo, 
UserRepository userRepo, PasswordEncoder encoder) { 





现在 ， 配 料 数据 会 在 dev 或 qa profile 激 活 的 时 候 才 加 载 。 这 意味 
者， 在 开 及 环境 运行 的 时 候 我 们 需要 将 dev profile 数 活 。 如 采 除 了 prod 激 
活 时 ，CommandLineRunner bean 者 需要 创建 ， 那 么 我 们 可 以 采用 一 种 更 
简便 的 方式 。 在 这 种 情况 下 ， 我 们 可 以 按照 如 下 的 方式 来 使 用 
(DProfije: 
6Bean 
@Profile("!prod") 


public CommandLineRunner dataLoader(IngredientRepository repo, 
UserRepository userRepo, PasswordEncoder encoder) { 





在 这 里 ， 感 叹 号 〈!) 否定 了 profile 的 名 称 。 实 际 上 ， 它 的 含义 是 只 
要 prod profile 不 激活 区 要 创建 CommandLineRunner bean。 


我 们 还 可 以 在 带 有 @Configuration 注 解 的 类 上 使 用 @Profile。 例 如 ， 
假设 我 们 要 将 CommandLineRunner 抽 取 到 一 个 名 为 DevelopmentConfig 的 
配置 类 中 ， 那 么 我 们 可 以 按照 如 下 的 方式 为 DevelopmentConfig 洪 加 
(OProfile: 





QProfile({"!prod", "lqga"}) 
@Configuration 
public class DevelopmentConfig { 


QBean 
public CommandLineRunner dataLoader(IngredientRepository repo, 
UserRepository userRepo, PasswordEncoder encoder) { 





在 这 里 ，CommandLineRunner bean 〈 包 括 DevelopmentConfig 中 有 定 
义 的 其 他 bean) 只 有 在 prod 和 qa 均 没有 激活 的 情况 下 才 会 创建 。 


5.4 ”小 结 


。 Spring bean9] 以 添加 @ConfigurationProperties 注 解 ， 这 样 就 能 够 从 
多 个 属性 源 中 选取 一 个 来 注入 它 的 值 。 

。 配置 属性 可 以 通过 命令 行 参 数 、 环 场 变 量 、JVM 系 统 属性 、 属 性 文 
件 或 YAML 文 件 等 方式 进行 设置 。 

。 配置 属性 可 以 用 来 复 兰 目 动 配 置 相 关 的 设置 ， 包 括 指 定数 据 源 URL 
和 和 日志 级 列 。 

。 Spring profile 可 以 与 属性 新 协同 使 用 ， 从 而 能 够 基于 激活 的 profile 
条 件 化 地 设置 配置 属性 。 


第 2 部 分 的 章节 将 会 涵盖 Spring 应 用 与 其 他 应 用 集成 的 话题 。 


第 6 和 草 将 扩展 第 2 章 对 Spring MVC 的 讨论 ， 介 绍 如 何在 Spring 中 编 与 
REST API。 我 们 将 会 看 到 如 何 使 用 Spring MVC 定 义 REST 冰 点、 局 用 超 
媒体 REST 资 源 以 及 使 用 Spring Data REST 上 自动 生成 基于 repository 的 
REST 端 点 。 第 7 章 转 换 视 角 ， 关 注 Spring 应 用 如 何 消 费 REST API 的 话 
题 。 在 第 8 章 中 ， 我 们 将 会 学 习 如 何 信 助 异步 通信 技术 让 Spring 及 大和 接 
收 Java Message Service (JMS) 、RabbitMQ 与 Kafka 的 消息 。 在 最 后 的 
第 9 章 中 ， 我 们 将 探讨 使 用 Spring Integration 项 目 实现 声明 式 应 用 集成 的 
话题 。 我 们 会 润 六 实 时 人 处理 数据 、 定 义 集成 流 以 及 与 外 部 系统 〈( 如 
Email 和 文件 系统 ) 集成 的 功能 。 


第 6 章 ”创建 REST 服 务 


。 在 Spring MVC 中 定义 REST 端 点 


。 局 用 超 链 接 REST 资 源 


。 自动 化 基于 repository 的 REST 端 点 





“Web 浏 览 冲 已 死 ， 那 么 现在 征 谁 的 天 下 呢 ? ” 


十 多 年 前 ， 我 就 昕 到 有 人 说 Web 浏 览 占 已 经 行将 就 木 ， 它 会 被 其 他 
的 事物 所 取代 。 但 是 ， 这 怎么 可 能 会 实现 呢 ? 谁 有 可 能 取代 几乎 无 处 不 
在 的 web 浏 览 器 呢 ? 如 果 没 有 Web 浏 览 器 ， 我 们 该 如 何 消费 越 来 越 多 的 
网 络 站 点 和 在 线 服务 呢 ? 这 肯定 是 条 个 狐 子 的 明言 乱 语 ! 


我 们 快 进 到 今天 ， 显 然 ，Web 浏 贤 如 并 没有 消失 ， 但 它 已 经 不 再 是 
访问 互联 网 的 主要 方式 了 。 现 在 ， 移 动 设备 、 平 板 电脑 、 智 能 手表 和 基 
于 语音 的 设备 已 经 非常 种 见 ， 甚 至 很 多 基于 浏览 器 的 应 用 实际 上 运行 的 
都 是 JavaScript 应 用 ， 而 不 再 是 让 浏览 恬 成 为 服务 器 演 染 内 容 的 哑 终 端 。 


随 着 客户 疹 的 可 选 方案 越 来 越 多 ， 许 多 应 用 程序 采用 了 一 种 通用 的 
设计 ， 那 吏 是 将 用 户 界 面 推 到 更 接近 客户 病 的 地 方 ， 而 让 服务 闪 公 开 
API， 通 过 这 种 API， 各 种 客户 疹 都 能 与 后 只 功 能 进行 区 互 。 


在 本 章 中 ， 我 们 将 会 使 用 Spring 来 为 Taco Cloud 应 用 提供 REST 
API。 在 这 里 我 们 将 会 用 到 第 2 章 中 已 经 学 习 过 的 Spring MVC， 使 用 
Spring MVC 的 控制 器 创建 RESTful 端 点 。 同 时 ， 我 们 还 会 将 第 4 章 中 定 
义 的 Spring Data repository 暴 露 为 REST 端 点 。 最 后 ， 我 们 将 会 看 一 下 如 
何 测 试 和 保护 这 些 顷 点。 首先 ， 我 们 需要 编写 儿 个 新 的 Spring MVC 控 制 
项， 它们 会 使 用 REST 奖 点 来 又 露 后 关 功 能 ， 这 些 关 点 将 会 被 一 Web 前 
闻 所 消 费 。 


6.1 编写 RESTful 控 制 器 


当 你 翻 看 本 章 并 阅读 简介 时 ， 束 会 发 现 我 重新 设想 了 Taco Cloud 的 
用 户 界 面 ， 布 望 你 不 要 介意 。 你 之 前 的 工作 成 果 可 能 比较 适合 起 步 ， 但 
是 在 美学 方面 也 许 会 有 所 人 欠缺。 


图 6.1 是 狐 的 Taco Cloud 外 观 的 示例 ， 看 上 去 很 时 尚 吧 ? 
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Where taco hunger meets taco creativity 


We love tacos.All kinds of tacos. And we love being 
creative with the way we make our tacos. 


Some taco joints offer a set finite menu of tacos to 
choose from. At Taco Cloud, we want to share the joy 
of taco creativity with you, allowing you to design your 
own tacos from a palette of fresh and delicious 
ingredients. While we may offer some of our creations 
for you to try, the real fun is when you create your 
own tortilla-wrapped works of art. 


And, even though we love tacos and creativity, we 
prefer to avoid doing complex math. That's why all 
tacos are priced modestly at $4.99 each, no matter 
how many or what ingredients you choose. 





Click here to get started on your taco masterpiece! 


To learn more about Taco read 





图 6.1 新 的 Taco Cloud 主 页 
在 改善 Taco Cloud 外 观 的 同时 ， 我 还 决定 使 用 流行 的 Angular 框 架 将 
前 闹 构 建 为 单 页 应 用 。 最 终 ， 这 个 新 的 浏 只 器 UI 将 瞪 换 我 们 在 第 2 半 中 
创建 的 服务 占 演 染 页 面 。 但 是 ， 想 要 实现 这 一 点 ， 我 们 需要 创建 一 个 
REST API， 基 于 Angulart 咱 的 UI 将 会 与 之 通信 ， 以 保存 和 获取 taco 数 据 。 


是 售 要 及 用 SPA? 


在 第 2 章 中 ， 我 们 使 用 Spring MVC 开 发 了 一 个 传统 的 多 页 应 
用 (MultiPage Application，MPA) ， 现 在 我 们 要 将 其 符 换 为 基 
于 Angular 的 单 页 应 用 (Single-Page Application，SPA) 。 但 是 ， 





我 并 不 认为 SPA 始 终 是 比 MPA 更 好 的 可 选 方案 。 


在 SPA 中 ， 展 现 和 后 站 处 理 在 很 大 程度 上 走 解 炎 的 ， 这 样 束 
提供 了 为 相同 的 后 闯 功 能 开 及 多 个 用 户 界 面 《“ 例 如 原生 移动 应 
用 ) 的 机 会 。 它 还 为 与 其 他 可 以 使 用 API 的 应 用 程序 集成 创造 了 


可 能 性 。 但 并 不 是 所 有 的 应 用 程序 都 需要 这 种 灵活 性 ， 如 果 你 只 
再 要 在 Web 页 面 上 显示 信息 ， 那 么 MPA 是 一 种 更 简单 的 设计 。 





这 并 不 一 本 关于 Angular 的 书 ， 所 以 本 和 草 中 的 代码 将 会 主要 关注 后 
内 的 Spring 代码 。 我 只 会 给 出 适当 的 Angular 代 码 ， 以 便于 让 你 了 解 客 户 
痕 是 如 何 运 行 的 。 但 是 ， 请 放心 ， 完 整 的 代 但 集会 包括 Angular 亲 痪 ， 
它们 都 是 本 书 配 套 代 码 的 一 部 分 。 如 有 果 你 有 兴趣 ， 可 以 阅读 Jeremy 
Wilken 编 写 的 Angular in Action (Manning，2018)〉 以 及 Yakov Fain 和 
Anton Moiseev 编 写 的 Angular Development with TypeScript, Second 
Fdition (Manning, 2018) 。 


本 质 上 来 讲 ，Angular 各 户 交 代码 将 会 通过 HTTP 请 求 与 本 章 所 创建 
时 API 进 行 通 信 。 在 第 2 半 中 ， 我 们 使 用 @GetMapping 注 解 从 服务 病 获 取 
数据 ， 使 用 @PostMapping 注 解 往 服务 句 闹 提交 数据 。 在 定义 REST API 
的 时 候 ， 这 些 注解 依然 有 用 。 除 此 之 外 ，Spring MVC 还 为 各 种 类 型 的 
HTTP 请 求 提 供 了 一 些 其 他 的 注解 ， 如 表 6.1 所 示 。 


表 6.1 ”Spring MVC 的 HTTP 请 求 处 理 注解 


注解 HTTP 方 法 典型 用 途 


@RequestMapping | 通用 的 请 求 处 理 ，HTTP 方 法 可 以 通过 method 声 明 





“将 HTTP 方 法 映射 为 创建 、 读 取 、 更 新 和 删除 《CRUD ) 操作 并 不 是 非常 恰当 ， 但 是 在 实践 中 
这 是 常见 的 使 用 方式 ， 在 我 们 的 Taco Cloud 应 用 中 也 是 这 样 使 用 它们 的 。 


要 实际 看 到 这 些 注 解 的 效果 ， 我 们 十 要 创建 一 个 简单 的 REST 闹 


点 ， 广 关 点 会 检索 一 些 最 新 创建 的 taco。 
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6.1.1 从 服务 者 中 检索 数据 


Taco Cloud 应 用 最 酪 的 一 件 事 束 是 它 允 许 taco 迷 设计 目 己 的 taco 作 
品 ， 并 与 taco 爱 好 者 分 享 他 们 的 作品 。 为 此 ，Taco Cloud 需 要 能 够 在 单 
击 “Latest Designs” 链 接 时 显示 最 近 创 建 的 taco 列 表 。 


在 Angular 代 码 中 ， 我 定义 了 RecentTacosComponent 组 件 ， 它 会 展现 


最 新 创建 的 taco。RecentTacosComponent 完 整 的 TypeScript 代 码 如 程序 清 
单 6.1 所 示 。 


程序 清单 6.1 展现 最 近 taco 的 Angular 组 件 


Import { Component, OnInit, Injectable } from ‘'@Qangular/core'; 
import { Http 上 from ‘'@angular/http'; 
import { HttpClient } from ‘'@angular/common/http'; 


@Component({ 
selector: ‘recent-tacos', 
templateUrl: ‘recents.component.html’', 
styleUrls: | ./recents.component .css | 


}) 
@Injectablel) 
export class RecentTacosComponent implements OnInit { 


recentiacos: any; 


constructor(private httpClient: HttpClient) { } 


ngOnInit() { 
this.httpClient.get('http://localhost:8686/design/recent') 一 --- 从 服务 
釉 问 获取 最 近 的 taco 
.Subscribe(data => this.recentTacos = data) ; 


} 





} 


我 们 需要 关注 ngOnInit() 方 法 。 在 这 个 方法 中 ， 
RecentTacosComponent 使 用 注入 的 Http 模 块 来 针对 
http://localhost:8080/design/recent 地 址 发 送 HTTP GET 请 求 ， 并 期 望 得 到 
一 个 包含 taco 设 计 的 列表 ， 它 们 会 补 放 到 名 为 recentTacos 的 模型 属性 
中 。 视 图 《在 recents.component.html 中 ) 会 将 模型 数据 展现 为 HIMEL 的 
形式 ， 以 便于 在 浏览 器 中 泻 染 。 在 创建 完 3 个 taco 之 后 ， 最 终 的 结果 如 图 
6.2 所 不 。 





localhost 


= 
DESIGN A TACO SIGNIN Vv 里 $0.00 


Latest designs Specials Locations 


Admire some recently created taco masterpieces 


Even the greatest artists sometimes need to be inspired by the works of others. Here are some of the 
most recently created tacos, designed by taco artists just like you... 


a The The 产 The 
"Veg-DOut” "Bovine Bounty” "Carnivore” 

Diced Tomatoes, Lettuce and Salsa Ground Beef, Cheddar, Monterrey Jack Ground Beef, Carnitas, Sour Cream, 
wrapped in a Flour Tortilla and a Corn and Sour Cream wrapped in a Corn Salsa and Cheddar wrapped in a Flour 
Tordilla Tordilla Tordlla 

Order this taco Order this taco Order this taco 


To learn more about Taco Cloud read Spring in Action, 5th Ediion 


图 6.2 ”展现 最 近 创建 的 taco 


在 我 们 的 拼 独 中， 缺失 的 一 部 分 束 是 端点 ， 筷 会 处 理 针 
对 “/design/recent” 的 HTTP GET 请 求 并 将 最 近 设 计 的 taco 列 表 作 为 啊 应 。 
我 们 需要 创建 一 个 新 的 控制 喜来 处 理 这 种 请 求 。 程 序 清单 6.2 展 现 了 完 
成 该 任务 的 控制 天 


程序 清单 6.2” 处理 taco 设 计 API 请 求 的 RESTful 控 制 器 





package tacos .web.api; 


import 


import 
import 
import 
import 
import 
import 
import 
import 


Java.util.Optional,; 


org. 
org. 
org. 
org. 
org. 
org. 
org. 
org. 


springframework. 
springframework. 
springframework. 
springframework. 
.http .HttpStatus ; 
springframework. 
springframework. 
springframework. 


springframework 


beans.factory.annotation.Autowired; 
data.domain.PageRequest; 
data.domain.Sort,; 

hateoas .EntityLinks ; 


web .blind.annotation.CrossOrigiln; 
web .bind.annotation.GetMapping; 
web .bind.annotation.PathVariable; 


Import org.springframework.web.bind.annotation.RequestMapping; 
Import org.springframework.web.bind.annotation.ResponseStatus; 
import org.sprIngframework.web.blind.annotation.RestController; 


import tacos.Taco; 
Import tacos.data.TacoRepository; 


QRestController 

@RequestMapping(path="/design", 和 一 --- 处 理 针 对 “/design” 的 请 求 
produces="application/json") 

@CrossOrigin(origins="*") 一 --- 人 允许 跨 域 请求 


public class DesignTacoController { 
private TacoRepository tacoRepo; 


QAutowired 
EntityLinks entityLinks; 


public DesignTacoController(TacoRepository tacoRepo) { 
this.tacoRepo = 七 CORepo ; 


} 
@QGetMapping("/recent") 
public Iterable<Taco> recentTacos() { 一 --- 获取 并 返回 最 近 设 计 的 
taco 
PageRequest page = PageRequest.of( 
80, 12, Sort.by("createdAt").descending()); 
return tacoRepo.findAll(page).getContent(); 


} 
} 


你 可 能 会 完 得 这 个 控制 占 oR 弟 珊 本。 在 第 2 半 中 ， 我 
们 创建 了 名 为 DesignTacoController 的 控制 器 ， 它 会 处 理 类 似 的 请 求 类 

但 是 ， 当 时 是 用 来 处 理 多 页 Taco Cloud 应 用 的 ， 这 个 新 的 
DesignTacoController 是 一 个 REST 控 制 项 ， 古 由 @RestController 注 解 声 明 
的 。 


@RestController 广 解 有 两 个 目的 。 首 先 ， 它 是 一 个 类 似 于 
@Controller 和 @Service 的 构造 型 注解 ， 能 够 让 类 被 组 件 扫 摘 功能 友 现 。 
但 是 ， 与 REST 最 密切 相关 之 处 在 于 ，@RestController 注 解 会 告诉 


Spring， 控 制 普 中 的 所 有 处 理 硕 方法 的 返回 人 都 要 直接 与 入 啊 应 体 中 ， 
而 不 是 将 值 放 到 模型 中 并 传递 给 一 个 视图 以 便于 进行 广 染 


作为 蔡 代 方案 ， 我 们 也 可 以 像 其 他 Spring MVC 控 制 右 那样 为 
DesignTacoController 深 加 @Controller 注 解 。 但 是 ， 这 样 的 十， 我 们 就 需 
要 为 每 个 处 理 器 方法 再 添加 @ResponseBody 注 解 ， 这 样 才能 达到 相同 的 
效果 。 另 外 一 种 方案 就 是 返回 ResponseEntity 对 象 ， 我 们 稍 后 将 会 对 其 
进行 讨论 。 


类 级 别 的 @RequestMapping 注 解 ， 册 加 上 recentTacos(0) 方 法 上 的 
@GetMapping 注 解 ， 两 者 结合 起 来 指定 recentTacos0) 方 法 将 会 负责 处 理 
针对 “designrecent” 的 GET 请 求 〈 这 也 正 是 Angular 代 但 所 需要 的 ) 。 


你 还 会 及 现 ，@RequestMapping 注 解 还 设置 了 一 个 produces 属性 。 
这 指明 DesignTacoController 中 的 所 有 处 理 器 方法 只 会 处 理 Accept 头 信息 
仿 “application/json” 的 请 求 。 它 不 仅 会 限制 API 只 会 生成 JSON 结 果 ， 
同时 还 允许 其 他 的 控制 磊 〈 比 如 第 2 章 中 的 DesignTacoController〉 处理 
Oe 同 路 径 的 请 求 ， 只 要 这 些 请 求 不 要 求 JSON 格 式 的 输出 束 可 以 。 

这 样 会 限制 API 是 基于 JSON 的 ， 但 是 我 们 还 可 以 将 produces 设 置 为 
is 的 数组 ， 这 样 的 话 束 允许 我 们 设置 多 个 内 容 关 型 。 比 
如 ， 为 了 多 许 生 成 XML 格 去 的 输出 ， 我 们 可 以 为 produces 属 性 还 


加 “text/xml”: 


@QRequestMapping(path="/design",， 





produces={"application/json", "text/xml"}) 


在 程序 清单 6.2 中 ， 你 可 能 还 及 现 这 个 类 添加 了 @CrossOrigin 注 解 。 
为 应 用 程序 的 Angular 部 分 将 会 运行 在 与 API 相 独立 的 主机 和 /或 端口 上 
(至 少 目前 是 这 样 的 ) ，Web 浏 贤 旨 会 阻止 Angular 客 户 闹 消费 该 API。 
我 们 可 以 在 服务 问 啊 应 中 放 加 CORS (Cross-Origin Resource Sharing， 跨 
域 资 源 共 人 至) 头 信 息 来 突破 这 一 限制 。Spring 借 助 @CrossOrigin 注 解 让 
CORS 的 使 用 更 加 简单。 正如 我 们 所 看 到 的 ，@CrossOrigin 允 许 来 日 任 
何 域 的 客 成 端 消 费 访 API。 


recentTacos() 方 法 中 的 逻辑 非 闸 简 捍 直 接 。 它 构建 了 一 个 
PageRequest 对 象 ， 指 明 我 们 想 要 第 一 页 〈 厅 与 为 0) 的 12 条 结果 ， 并 且 
要 按照 taco 的 创建 时 间 降 序 排列 。 简 而 言 之 ， 我 们 想 要 得 到 12 个 最 近 创 
建 的 taco 设 计 。PageRequest 会 被 传递 到 TacoRepository 的 findAl10 方 法 
中 ， 分 页 的 结果 内 容 则 会 返回 到 客户 并 (也 束 是 在 程序 消音 6.2 中 我 们 
所 看 到 的 ， 它 们 将 会 以 模型 数据 展现 给 用 户 ) 。 

现在 ， 假 设 我 们 想 要 提供 一 个 按照 DD 抓 取 单 个 taco 的 端点 。 通 过 在 
处 理 喜 方法 的 路 径 上 使 用 占 位 符 并 让 方法 接收 一 个 路 径 变 量 ， 我 们 能 人 够 
捕获 到 这 个 ID， 然 后 束 可 以 值 助 repository 合 找 Taco 对 象 了 : 


@QGetMapping("/{id}") 

public Taco tacoById(@PathVariable("id") Long id) { 
Optional<Taco> optTaco = tacoRepo.findById(id); 
if (optTaco.isPresent()) { 


return optTaco.get() ; 


return null; 





因为 控制 器 的 基础 路 径 是 “/design”， 所 以 这 个 控制 器 方法 处 理 的 是 


针对 “/design/{id}” 的 GET 请 求 ， 其 中 路 径 的 “{id}” 部 分 古 占 位 全。 请 求 
中 的 实际 值 将 会 传递 给 id 参 数 ， 它 通过 @PathVariable 注 和 解 与 {id} 占 位 符 
进行 匹配 。 


在 tacoById() 中 ，id 参 数 修 传 递 到 了 repository 的 findBy1d() 方 法 中 ， 
以 便于 抓 取 Taco。findById0 返 回 的 是 一 个 Optional<Taco>， 因 为 根据 给 
定 的 ID 可 能 获取 不 到 taco， 所 以 在 返回 值 的 时 候 我 们 需要 确定 葬 ID 坪 合 
能 够 匹配 一 个 taco。 如 果 能 够 上 匹配， 我们 可 以 调用 Optional<Taco> 对 象 
的 getO 方 法 返回 实际 的 Taco。 


如 果 访 ID 无 法 匹配 任何 已 知 的 taco， 我 们 将 会 返回 null。 但 是 ， 这 
种 做 法 并 不 完美 。 如 果 我 们 返回 null， 客 户 端 将 会 接收 到 空 的 响应 体 以 
及 值 为 200(OK) 的 HITP 状 态 码 。 客 户 靖 实际 上 接收 到 了 一 个 无 法 使 用 的 
啊 应 ， 但 是 状态 码 却 提示 一 切 正 常 。 有 一 种 更 好 的 方式 是 在 啊 应 中 使 用 
HTTP 404 (NOT FOUNDI) 状 态 。 


按照 现在 的 与 法， 我 们 没有 简单 的 途径 在 tacoById0 中 返回 404 状 
态 。 但 是 ， 如 采 我 们 做 一 些小 的 调整 ， 融 可 以 将 状态 码 设 置 成 很 恰当 的 
值 了: 

@GetMapping("/{id}") 
public ResponseEntity<Taco> tacoById(@PathVariable("id") Long id) { 


Optional<Taco> optTaco = tacoRepo.findById(id); 
if (optTaco.isPresent()) { 


return new ResponseEntity<>(optTaco.get()，HttpSstatus .OK ) ; 


} 
return new ResponseEntity<>(null, HttpStatus.NOT FOUND); 


} 





现在 ，tacoById0 返 回 的 不 是 一 个 Taco 对 象 ， 而 是 
ResponseEntity<Taco>。 如 果 找 到 taco， 我 们 束 将 Taco 包 疙 a 到 
ResponseEntity 中 ， 并 且 会 带 有 OK 的 HITP 状 态 〈 这 也 是 之 前 的 行 
为 )”。 如 果 找 不 到 taco， 我 们 束 将 会 在 ResponseEntity 中 包装 一 个 null， 
并 且 会 带 有 NOT FOUND 的 HITP 状 态 ， 从 而 表明 客户 站 试图 抓 取 的 taco 
并 不 存在 。 


我 们 已 经 有 了 面 同 Angular 和 多 户 问 的 初始 Taco Cloud API， 当 然 它 也 
可 以 用 于 其 他 类 型 的 客户 闹 。 在 开 友 中 ， 我 们 可 能 还 想 使 用 像 curl 或 
HTTPie 这 样 的 命令 行 工 具 来 探测 该 API。 比 如 ， 如 下 的 命令 行 展示 了 如 
何 通 过 curl 获 取 最 新 创建 的 taco: 


$ curl localhost:8686/design/recent 


如 果 你 更 喜欢 HTTPie， 那 如 下 所 示 : 


$ http :8686/design/recent 


定义 能 够 返回 信息 的 问 扣 仅 仪 是 第 一 步 。 如 来 我 们 的 API 和 需要 从 客 
户 站 接收 数据 义 该 怎么 从 呢 ? 接 下 来 ， 我 们 看 一 下 如 何 编写 控制 硕 来 处 
理 请 求 的 输入 。 


6.1.2 友 送 数据 到 服务 妖 六 


到 目前 为 止 ， 我 们 的 API 能 够 返回 多 个 最 近 创 建 的 taco。 但 是 ， 这 
些 taco 又 是 怎样 创建 的 呢 ? 


我 们 还 没有 删 挥 第 2 草 的 任何 代码 ， 所 以 原始 的 
DesignTacoController 还 存在 ， 它 会 展现 taco 的 设计 表单 并 处 理 表 单 的 提 
交 。 这 是 获取 测试 数据 来 验证 我 们 所 创建 的 API 的 一 个 好 办 法 。 如 果 我 
们 想 要 将 Taco Cloud 转 换 成 单 页 应 用 ， 那 么 我 们 需要 创建 Angular 组 件 以 
及 对 应 的 新 护 ， 以 此 来 玲 换 第 2 章 中 的 taco 设 计 表 时 。 


在 客户 闪 代 码 方面 ， 我 们 通过 一 个 名 为 DesignComponent〈 在 名 为 
design.component.ts 的 文件 中 ) 的 新 Angular 组 件 来 处 理 taco 设 计 表 单 。 
为 要 处 理 表 单 提 交 ， 上 所 以 DesignComponent 中 有 一 个 onSubmitO 方 法 ， 如 
下 所 示 : 


onSubmit() { 
this.httpClient.post( 
http:/ /localhost:8080/deslgn ， 
this.model, { 
headers: new HttpHeaders().set('Content-type', 'application/json 
'), 


}).subscribe(taco => this.cart.addToCart(taco)); 


this.router.navigate(['/cart" |); 





} 


在 onSubmitO 方 法 中 ， 我 们 调用 了 HttpClient 的 postO) 方 法 而 不 是 get0) 
方法 。 这 意味 看 我 们 不 再 是 从 API 中 抓 取 数 据 ， 而 是 同 API 发 送 数 据 。 
具体 来 讲 ， 我 们 将 一 个 taco 设 计 《 存 放 到 model 变 量 中 ) 借助 HTTP 
POST 请 求 友 送 人 至 “/design” 的 API 六 点 上 。 


此 ， 我 们 需要 在 DesignTacoController 中 编写 一 个 方法 处 理 该 请 求 
并 保存 该 taco 设 计 。 通 过 在 DesignTacoController 中 这 加 如 下 的 postTaco0) 
方法 ， 我 们 束 能 让 控制 闫 实现 该 功能 : 


@QPostMapping(consumes="application/json") 
@QResponseStatus(HttpStatus .CREATED) 


public Taco postTaco(@RequestBody Taco taco) { 
return tacoRepo.save(taco); 





} 


因为 postTaco() 将 会 处 理 HTTP POST 请 求 ， 所 以 它 使 用 了 
(@PostMapping 注 解 ， 而 不 是 @GetMapping。 在 这 里 ， 我 们 没有 指定 path 
属性 ， 因 此 按照 DesignTacoController 上 的 类 级 别 @RequestMapping 注 
解 ，postTaco0 方 法 将 会 处 理 对 “/design” 的 请 求 。 


但 是 ， 我 们 设置 了 consumes 属 性 。consumes 属 性 用 于 指定 请 求 输 
入 ， 而 produces 用 于 指定 请 求 输出 。 在 这 里 ， 我 们 使 用 consumes 属 性 ， 
表明 该 方法 只 会 处 理 Content-type 与 application/json 相 匹配 的 请 求 。 


方法 的 Taco 参 数 市 有 @RequestBody 注 解 ， 表 明 请 求 应 该 被 转换 为 
一 个 Taco 对 象 并 绑 定 到 该 参数 上 。 这 个 注解 是 pd 如 朵 没有 有 
它 ，Spring MVC 将 会 认为 我 们 布 望 将 请 求 参 数 〈 要 么 是 得 询 参 数 ， 要 人 么 
是 表单 参数 ) 绑 定 到 Taco 上 。 但 是 ， ER 
体 中 的 JSON 会 被 绑 定 到 Taco 对 月 上 。 


在 postTaco0 接 收 到 Taco 对 象 之 后 ， 了 驶 会 将 该 对 象 传递 给 
TacoRepository 的 save0) 方 法 。 


你 可 能 也 注意 到 了 ， 我 为 postTaco(0) 方 法 添加 了 
(@ResponseStatus(HttpStatus.CREATED) 注 解 。 在 正常 的 情况 下 (没有 异 
常 抛 出 的 时 候 ) ， 所 有 响应 的 HTTP 状 态 码 都 是 200 (OK)， 表 明 请 求 是 
成 功 的 。 尽 管 我 们 始终 都 希望 得 到 HTTP 200， 但 是 有 些 时 候 它 的 描述 


性 不 足 。 在 POST 请 求 的 情况 下 ，201 (CREATED) 的 HTTP 状 态 更 具有 描 
述 性 。 它 会 告诉 各 户 靖 ， 请 求 不 仅 成 功 了 了 ， 还 创建 了 一 个 资产。 在 适当 
的 地 方 使 用 @ResponseStatus 将 了 最 具 摘 述 性 和 最 精确 的 HITP 状 态 码 传递 
给 客户 闯 是 一 种 更 好 的 做 法 。 


我 们 已 经 使 用 @PostMapping 创 建 了 新 的 Taco 资 源 ， 除 此 之 外 ， 
POST 请 求 还 能 用 来 更 新 资源 。 尺 官 如 此 ，POST 请 求 通 当 用 来 创建 次 
源 ， 而 PUT 和 PATCH 请 求 退 常用 来 更 新 资源 。 接 下 来 ， 让 我 们 看 一 下 流 
如 何 使 用 @PutMapping 和 (@PatchMapping 来 更 新 数据 。 


6.1.3 ”在 服务 左上 更 新 数据 


在 编写 控制 器 来 处 理 HTTP PUT 或 PATCH 命令 之 前 ， 我 们 应 该 花 点 
时 间 直 和 面 这 个 问题 ， 为 什么 会 有 两 种 不 同 的 HITP 方 法 来 更 新 资源 ? 


尺 官 PUT 经 常 被 用 来 更 新 资源 ， 但 它 在 语义 上 其 实 是 GET 的 对 立 
面 。GET 请 求 用 来 从 服务 问 往 客 尸 闹 传 输 数 据 ， 而 PUT 请 求 则 是 从 客户 
曾 往 服务 问 发 这 数 据 。 

从 这 个 音义 上 讲 ，PUT 真 正 的 目的 是 执行 大 规模 的 蔡 换 

(replacement) 操作 ， 而 不 是 更 新 操作 。HTTP PATCH 的 目的 是 对 资源 
数据 打 补 丁 或 局 部 更 新 。 


例如 ， 假 设 我 们 想 要 更 新 茶 个 订单 的 地 址 信息 。 信 助 REST APT， 
其 中 有 一 种 实现 方式 就 是 借助 如 下 所 示 的 PUT 请 求 处 理 器 : 


@PutMapping("/{orderId}") 
public Order putOrder(@RequestBody Order order) { 


return repo.save(order); 


} 





这 种 方式 可 以 运行 ， 但 是 它 可 能 需要 客户 端 将 完整 的 订单 数据 从 
PUT 请 求 中 提交 上 来 。 从 语义 上 讲 ，PUT 意 味 着 “将 数据 放 到 这 个 URL 
上 ”， 其 本 质 上 了 吏 是 奉 换 已 有 的 数据 。 如 果 省 略 了 订单 上 的 荣 个 属性 ， 
那么 该 属性 的 值 应 该 被 null 所 履 辣 ， 甚 至 订单 中 的 taco 也 需要 和 订单 数 
据 一 起 设置 ， 人 否则 ， 它 们 将 会 从 订单 中 移 除 。 


如 东 PUT 请 求 所 做 的 是 对 资源 数据 的 大 规模 谷 搞 ， 那 么 我 们 该 如 何 
处 理 局 部 更 新 的 请 求 呢 ?这 就 是 HTTP PATCH 请 求 和 Spring 的 
@PatchMapping 注 解 所 擅长 的 事情 了 。 如 下 展示 了 如 何 编写 控制 套 方 法 
来 处 理 订单 的 PATCH 请 求 : 
@PatchMapping(path="/{orderId}", consumes="application/json") 
public Order patchOrder(@PathVariable("orderId") Long orderId, 
QRequestBody Order patch) { 
Order order = repo.findById(orderId).get(); 
if (patch.getDeliveryName() != null) { 


order.setDeliveryName(patch.getDeliveryName()); 


} 
if (patch.getDeliveryStreet() != null) { 
order.setDeliveryStreet(patch.getDeliveryStreet()); 


} 
if (patch.getDeliveryCity() != null) { 
order.setDeliveryCity(patch.getDeliveryCity()); 


} 
if (patch.getDeliveryState() != null) { 
order.setDeliveryState(patch.getDeliveryState( )); 


if (patch.getDeliveryZip() != null) { 
order.setDeliveryZip(patch.getDeliveryState()); 


} 
if (patch.getCcNumber() != null) { 


order .setCcNumber(patch .getCcNumber() ) ; 


if (patch.getCcExpiration() != null) { 
order.setCcExpiration(patch.getCcExpiration()); 


} 

if (patch.getCcCVV() != null) { 
order.setCcCVV(patch.getCcCVV()); 

} 


return repo.save(order); 





这 里 需要 关注 的 第 一 件 事情 束 是 patchOrder0) 方 法 使 用 了 
(@PatchMapping 注 解 ， 而 不 是 @PutMapping 注 解 ， 这 表示 它 应 该 处 理 
HTTP PATCH 请 求 ， 而 不 是 PUT 请 求 。 


有 一 点 你 肯定 也 注意 到 了 ， 那 就 是 patchOrder0 方 法 比 putOrderO 方 
法 要 更 复杂 一 些 。 这 是 因为 Spring MVC 的 映射 注解 ， 虽 然 包 括 了 
@PatchMapping 和 CQ@PutMapping， 但 是 它们 只 能 用 来 指定 菜 个 方法 能 够 
处 理 什 么 类 型 的 请 求 ， 这 些 注 解 并 没有 规定 该 如 何 处 理 请 求 ， 尺 管 
PATCH 在 语义 上 代表 局 部 更 新 ， 但 是 在 处 理 硕 方法 中 实际 编号 代 但 执 
行 更 新 的 还 是 我 们 目 己 。 


对 于 putOrder0) 方 法 来 说 ， 我 们 得 到 的 是 完整 的 订单 数据 ， 人 然后 将 
它 保 存 起 来 ， 这 样 就 完全 符合 HTTP PUT 的 语义 。 但 是 ， 对 于 
patchMapping() 来 说 ， 为 了 符合 HTTP PATCH 的 语义 ， 方 法 体 需 要 更 多 
的 乔 芒 才 行 。 在 这 里 ， 我 们 不 是 用 刹 友 送 过 来 的 数据 完全 丛 换 已 有 的 订 
羊 ， 而 是 探 租 传 入 Order 对 象 的 每 个 字段 ， 并 将 所 有 非 aull 的 全 应 用 到 已 
有 的 订 蛙 上 。 这 种 方式 允许 客户 咽 只 发 送 要 改变 的 属性 束 可 以 ， 并 且 对 
于 客户 病 没 有 指定 的 属性 ， 服 务 器 问 会 你 留 已 有 的 数据 。 


还 有 更 多 的 方式 来 实现 PATCH 


patchOrder0) 方 法 中 的 PATCH 操作 还 有 一 些 限 制 : 


如 果 null 意 味 着 没有 变化 ， 那 么 客户 端 该 如 何 指定 一 个 字段 
真 的 要 设置 为 null? 


我 们 没有 办 法 移 除 或 添加 集合 的 子 集 。 如 果 客 户 端 想 要 添加 
或 移 除 集合 中 的 条 日， 那么 它 必须 将 变更 的 完整 集合 发 送 到 
服务 器 病 。 


天 于 PATCH 请 求 该 如何 处 理 以 及 传 入 的 数据 该 是 什么 样子 
并 没有 硬性 的 规定 。 客 户 冰 可 以 及 送 一 个 PATCH 请 求 特定 的 变 
更 描述 ， 而 不 是 发送 真正 的 领域 数据 。 当 然 ， 如 末 是 这 样 ， 那 么 
请 求 处 理 器 方法 束 会 改写 为 处 理 patch 指 令 ， 而 不 是 领域 数据 。 


在 @PutMapping 和 @PatchMapping 中 ， 需 要 注意 引用 的 请 求 路 径 都 
是 要 进行 变更 的 资源 。 这 与 @GetMapping 注 解 标 注 的 方法 在 处 理 路 径 时 
的 方式 是 相同 的 。 

我 们 已 经 看 过 了 如 何 使 用 @GetMapping 和 (@PostMapping 获 取 和 友 


送 资 源 。 同 时 ， 也 看 到 了 使 用 @PutMapping 和 人 C@PatchMapping 更 新 资源 
的 两 种 方式 。 剩 下 的 了 吏 是 访 如 何 处 理 删 除 资 源 的 请 求 了 。 


6.1.4 删除 服务 从 上 的 数据 


有 时 ， 有 些 数据 可 能 不 再 需要 了 。 在 这 种 场景 下 ， 客 户 凯 应 该 能 够 
通过 HTTP DELETE 请 求 的 形式 要 求 移 除 某 个 资源 。 


Spring MVC 的 @DeleteMapping 注 解 能 够 非 间 便利 地 声明 处 理 
DELETE 请 求 的 方法 。 例 如 ， 我 们 想 要 本 个 能 够 删除 订单 资源 的 
API。 如 下 的 控制 硕 方 法 就 能 做 到 这 一 点 


@QDeleteMapping("/{orderId}") 
@ResponseStatus(code=HttpStatus.NO CONTENT) 
public void deleteOrder(@PathVariable("orderId") Long orderId) { 


try { 
repo.deleteById(orderId); 


} catch (EmptyResultDataAccessException e) {} 





} 


现在 ， 青 问 你 解释 这 个 映射 注解 束 有 些 哆 唆 了。 我 们 已 经 见 过 了 
@OGetMapping、@PostMapping、@PutMapping 和 人 @PatchMapping， 每 个 
注解 都 能 够 指定 菏 个 方法 可 以 处 理 对 应 类 型 的 HITP 请 求 。 坚 无 疑问 ， 
(@DeleteMapping 会 指定 deleteOrder() 方 法 负 贡 处 理 针 
对 “orders/{forderId}” 的 DELETE 请 求 。 


这 个 方法 中 的 代码 会 负责 真正 删除 订单 。 在 本 例 中 ， 它 会 接收 订单 
ID 并 将 其 传 递 给 repository 的 deleteById0) 方 法 ， 其 中 这 个 ID 是 以 UREL 中 
路 径 变 量 的 形式 提供 的 。 如 琳 方 法 调用 的 时 候 该 订单 存在 ， 残 将 会 删除 
这 个 订单 。 如 末 订 单 不 存在 ， 残 会 抛 出 


EmptyResujtDataAccessEXception 。 


在 这 里 ， 我 选择 捕获 该 EmptyResultDataAccessEXxception 弄 曲 ， 但 是 
什么 都 没有 做 。 在 这 里 ， 我 的 想法 是 如 果 你 答 试 删除 一 个 并 不 存在 的 资 
源 ， 那 么 它 的 结果 和 删除 之 前 存在 这 个 资源 是 一 样 的 。 也 就 是 ， 最 终 的 
效 来 都 征 资 源 不 复 人 存在。 所 以 在 删除 之 前 资源 征 售 存在 并 不 重要 。 态 外 
一 种 办 法 束 是 可 以 让 deleteOrder() 返 回 ResponseEntity， 在 资源 不 存在 的 
时 候 将 响应 体 设 置 为 nmull 并 将 HTTP 状 态 码 设置 为 NOT FOUND。 


deleteOrder0) 方 法 唯一 需要 注意 的 是 它 使 用 了 @ResponseStatus 注 
解 ， 以 确保 响应 的 HITP 状 态 码 为 204 (NO CONTENT) 。 对 于 已 经 不 
存在 的 资源 ， 我 们 没有 必要 返回 任何 的 资源 数据 给 客户 疾 ， 因 此 
DELETE 请 求 通 间 并 设 有 啊 应 体 ， 我 们 需要 以 HITP 状 态 码 的 形 却 让 客 
户 交 知道 不 要 期 望 得 到 任何 的 凡 容 。 


现在 ，Taco Cloud API 己 经 基本 成 形 了 。 各 户 妆 的 代码 可 以 很 容易 
地 消费 我 们 的 API， 以 便于 显示 配料 、 接 收 订单 和 展示 最 近 创建 的 
taco。 但 是 ， 我 们 还 可 以 更 进一步 ， 让 API 更 易于 各 刀 妆 消费 。 接 下 
来 ， 我 们 看 一 下 如 何 为 Taco Cloud API 添 加 超 媒 体 功 能 。 


6.2 ”局 用 超 媒 体 


到 目前 为 止 ， 我 们 所 创建 的 API 非 常 简单， 但 是 只 要 消费 它 的 客户 
问 知 道 API 的 URL 模 式 ， 它 们 束 可 以 正和 党 运行。 例如， 客户 问 可 能 会 以 
便 编 码 的 形式 对 “design/recent” 发 送 GET 请 求 ， 以 便于 获取 最 近 创 建 的 
taco。 类 似 的 ， 客 尸 问 会 以 便 编 码 的 形式 将 taco 列 表 中 的 ID 拼 接 
到 “design” 上 形成 获取 特定 taco 资 源 的 URL。 


在 API 客 户 端 编码 中 ， 使 用 硬 编码 模式 和 字符 串 操 作 是 很 常见 的 。 
但 是 ， 我 们 设想 一 下 ， 如 果 API 的 URL 模 式 发 生 了 变化 又 会 怎么 样 呢 ? 
便 编码 的 客户 端 代码 掌握 的 依然 是 旧 的 API 信 息 ， 因 此 客户 端 代码 将 无 
法 正常 运行 。 对 API URL 进 行 便 编码 和 字符 串 操作 会 让 客户 问 代 人 码 变 得 
很 鹏 弱 。 


超 媒 体 作为 应 用 状态 引 敬 (Hypermedia as the Engine of Application 
State，HATEOAS) 是 一 种 创建 自 描述 API 的 方式 。API 所 返回 的 资源 中 
会 包含 相关 资源 的 链接 ， 客 户 问 只 需要 了 解 最 少 的 API URL 信 息 束 能 导 
航 整个 API。 这 种 方式 能 够 掌握 API 所 提供 的 资源 之 间 的 关系 ， 客 户 端 
能 够 基于 API 的 UREL 中 所 发 现 的 关系 对 它们 进行 壳 历 。 


举例 来 说， 假设 某 个 客户 端 想 要 请 求 最 近 设 计 的 taco 的 列表 ， 按 照 
原 她 的 形式 ， 在 没有 超 链 接 的 情况 下 ， 客 刻 问 以 JSON 格 式 接收 到 的 taco 
列表 会 如 下 所 示 《〈 为 了 简洁 ， 这 里 只 保留 了 第 一 个 taco， 剩 余 的 省 略 
本 


"id": 4， 
-name :  Veg-Out ， 
"createdAt": "206018-61-31T206:15:53.219+686060"， 
"ingredients": | 

id": "FLTO", "name": "Flour Tortilla", "type": "WRAP"}, 

"COTO", "name": "Corn Tortilla", “type": "WRAP"}, 

EEC 
"SLSA" 


"name": "Lettuce", "type": "VEGGIES"}, 
"name": "Salsa", "type": "SAUCE"} 


2 
2 
"TMTO", "name": "Diced Tomatoes", "type": "VEGGIES"}, 
2 
2 





如 果 客 户 端 想 要 获取 某 个 taco 或 者 对 其 进行 其 他 HTTP 操 作 ， 就 需要 
ideeren lmao 2 


Ns 


如 果 客 尸 问 想 要 对 祭 个 配料 执行 HTTP 请 求 ， 束 需要 将 该 配料 


id 属 性 的 值 拼接 到 路 径 为 “/ingredients” 的 URL 上 。 在 这 两 种 情况 下 ， 都 
需要 在 路 答 上 添加 “http:/”? 或 “https:/? 前 缀 以 及 API 的 主机 名 。 


如 果 API 启 用 了 超 媒 体 功 能 ， 那 么 API 将 会 描述 自己 的 URL， 从 而 
Wwe heen 如 果 骨 入 超 链 接 ， 那 么 最 近 创 建 的 
taco 列 表 将 会 如 程序 清单 6.3 所 示 。 


程序 清单 6.3 ”包含 超 链 接 的 taco 资 源 列 表 


”embedded : { 
"tacoResourcelList": | 


{ 


-name :  Veg-Out ， 
"createdAt": “2018-01-31T26:15:53.219+0006 ” ， 
"ingredients": | 


{ 
“name : "Flour Tortilla", 上 type : "WRAP", 
" links": { 
"self": { "href": "http://localhost:80608060/ingredients/FLTO" } 


"name": "Corn Tortilla", 上 type : "WRAP", 
" links": { 
"self": { "href": "http://localhost:8060806/ingredients/COTO"” } 


"name": "Diced Tomatoes ， "type": "VEGGIES", 


"self": { "href": "http://localhost:806806/ingredients/TMTO" } 


name : “Lettuce ` ， “type": “VEGGIES  ， 


"self": { "href": “http:// localhost:8686/ingredients/LETC”} 


"name": "Salsa", “type": "SAUCE", 


"self": { "href": "http://localhost:806806/ingredients/SLSA" } 


} 
} 
] ， 
" links": { 
"self": { "href": "http://localhost:806806/design/4" } 
} 
}, 
] 
}, 
" links": { 


"recents": 1{ 
"href": "http://localhost:8060806/design/recent" 


} 
} 
} 


这 种 特殊 风格 的 HATEOAS 衫 称 为 HAL《〈 超 文本 应 用 语言 ， 
Hypertext Application Language) 。 这 是 一 种 在 JSON 啊 应 中 能 入 超 链 接 
的 简单 通用 格式 。 


虽然 这 个 列表 看 上 去 不 保 前 面 那样 人 简洁， 但 是 它 确 实 提供 了 一 些 有 有 
用 的 信息 。 这 个 新 taco 列 表 中 的 每 个 元 系 都 包含 了 一 个 名 为 “_links” 的 属 
性 ， 为 客户 问 提 供 导 航 API 的 超 链接 。 在 本 例 中 ，taco 和 配料 都 有 一 
个 “selfP 链 接 ， 用 来 引用 该 资源 ;整个 列表 有 一 个 “recents” 链 接 ， 用 来 引 
用 该 API 自 身 。 


如 果 客 户 端 应 用 需要 对 列表 中 的 taco 执 行 HITTP 请 求 ， 那 么 在 开发 的 


时 候 不 需要 关心 taco 资 源 的 URL 是 什么 样子 。 相 反 ， 它 只 需要 请 

求 “sel 邓 链接 了 驶 可 以 了 ， 该 属性 将 会 映射 到 

http://localhost:8080/design/4。 如 果 客 户 闹 想 要 处 理 特定 的 配料 ， 只 需要 
查找 该 配料 的 “self” 链 接 即 可 。 


Spring HATEOAS 项 目 为 Spring 所 供 了 超 链 接 的 文 持 。 它 提供 了 一 
些 关 和 资源 痛 配 硕 〈assembler) ， 在 Spring MVC 控 制 闫 返回 资源 之 鲁能 
够 为 其 添加 链接 。 


为 了 在 Taco Cloud API 中 局 用 超 媒 体 功 能 ， 我 们 需要 在 构建 文件 中 
还 加 如 下 的 Spring HATEOAS starter 依 赖 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-hateoas</artifactId> 
</dependency> 





这 个 starter 不 仅 会 将 Spring HATEOAS 添 加 到 项 目的 类 路 径 中 ， 还 会 
提供 自动 配置 功能 以 启用 Spring HATEOAS。 我 们 所 需要 做 的 就 是 重新 


实现 控制 项 ， 让 它们 返回 资源 区 型 ， 而 不 是 领域 类 型 。 


我 们 首先 为 最 近 taco 列 表 琴 加 超 链接 ， 也 驳 是 针对 “design/recent” 的 
GET 请 求 。 
6.2.1 ”添加 超 链接 


Spring HATEOAS 提 供 了 两 个 主要 的 类 型 来 表示 超 链接 资源 : 


Resource 和 Resources。Resource 代 表 一 个 资源 ， 而 Resources 代 表 资 源 的 
集合 。 这 两 种 类 型 都 能 携 珊 到 其 他 资源 的 链接 。 当 从 Spring MVC REST 
控制 似 返 回 时 ， 它 们 所 携带 的 链接 将 会 包 售 到 客户 靖 所 接收 到 的 

JSON (或 XML) 中 。 


为 了 给 最 近 创 建 的 taco 洪 加 超 链 接 ， 我 们 需要 重 狐 实现 程序 清早 6.2 
中 的 recentTacos(0) 方 法 。 原 始 的 实现 返回 的 是 List<Taco>， 当 时 这 种 返回 
值 是 可 以 的 ， 但 是 现在 我 们 需要 让 它 返 回 Resources 对 象 。 程 序 清 单 6.4 
展示 了 recentTacos() 的 新 实现 ， 包 含 了 在 最 近 taco 列 表 中 局 用 超 链 接 的 第 


— 人 人 


I 
少 。 
程序 清单 6.4 ”为 资源 添加 超 链 接 


@QGetMapping("/recent") 
public Resources<Resource<Taco>> recentTacos() { 
PageRequest page = PageRequest.of( 
80, 12, Sort.by("createdAt").descending()); 


List<Taco> tacos = tacoRepo.findAll(page).getContent(); 


Resources<Resource<Taco>> recentResources = Resources.wrap(tacos); 


recentResources.add( 
new Link("http://localhost:80686/design/recent", "recents")); 
return recentResources,; 





在 这 个 狐 版 本 的 recentTacos() 中 ， 我 们 不 再 直接 人 返回 taco 的 列表 ， 而 
是 使 用 Resources.wrap() 将 taco 列 表 包 闭 为 Resources<Resource<Taco>>， 
并 使 其 作为 访 方 法 最 终 的 返回 值 。 但 是 在 Resources 对 象 返 回 之 前 ， 我 们 
次 加 了 名 为 recents 的 天 联 头 系 ， 它 的 URL 广 
http:/localhost:8080/design/recent。 这 样 做 的 结果 了 驶 是 ，API 请 求 所 返回 


的 资源 中 将 会 包含 如 下 的 JSON 片 段 : 


" links": { 
"recents": { 


"href": "http://localhost:8060806/design/recent" 
} 


} 





是 一 个 很 好 的 起 点 ， 但 是 我 们 还 有 一 些 事情 需要 和 完成。 现在， 我 
们 只 po ante 还 没有 为 taco 资 源 本 里 以 及 每 个 taco 
中 的 配料 添加 链接 。 我 们 很 快 束 会 实现 该 功能 ， 但 是 在 此 之 前 ， 我 们 要 
先 解 决 recents 链 接 中 的 便 编码 问题 。 


像 这 样 对 URL 进 行 便 编 码 是 一 种 很 糟 料 的 办 法 。 除 非 Taco Cloud 的 
目标 仅 限 于 在 本 地 开 友 机 器 上 运行 应 用 ， 合 则 ， 我 们 需要 找 一 种 方式 避 
免 在 UREL 中 使 用 便 编 码 的 localhost:8080。 科 和 运 的 是 ，Spring HATEOAS 
以 链接 构建 者 〈link builder) 的 方式 为 我 们 提供 了 帮助 。 


在 Spring HATEOAS 中 ， 最 有 用 建 痢 走 
ControllerLinkBuilder。 0 建 者 非常 镶 能 ， 它 能 上 自动 探知 主机 名 
是 什么 ， 这 样 束 能 避免 对 其 进行 便 编码 。 同 时 ， 它 还 提供 了 流畅 的 
oot 


信 助 ControllerLinkBuilder， 我 们 可 以 将 recentTacosO) 中 便 编 码 的 
Link 创 建 改 造成 如 下 的 形式 : 


Resources<Resource<Taco>> recentResources = Resources.wrap(tacos); 
recentResources.add( 


ControllerLinkBuilder.linkTo(DesignTacoController.class) 
.Slash("recent") 
.withRel("recents")); 





我 们 不 仪 不 需要 便 编 码 主机 名 ， 而 且 不 再 需要 指定 “/design”。 在 这 
里 ， 我 们 同 DesignTacoController 请 求 获 取 一 个 链接 ， 它 的 基础 路 径 
为 “design”。ControllerLinkBuilder 使 用 控制 硕 的 基础 路 径 作 为 我 们 创建 
的 Link 对 象 的 基础 。 


接 下 来 ， 调 用 了 在 Spring 项 目 中 我 最 喜欢 的 一 个 方法 : slashO。 我 
喜欢 这 个 方法 的 原因 是 这 个 方法 非 钊 简洁 地 描述 了 它 要 做 的 事情 。 这 个 
方法 会 为 URL 洪 加 和 儿 线 (/) 和 给 定 的 值 ， 所 形成 的 UREL 路 径 


是 “/design/recent”。 


有 最后， 我们 为 Link 指 定 了 一 个 关系 名 。 在 本 例 中 ， 天 系 名 为 


recents。 


尽 和 党 我 是 slash0O 的 忠实 粉丝 ， 但 是 ControllerLinkBuilder 还 有 另外 一 
个 方法 ， 能 够 消除 链接 URL 上 的 所 有 便 编 码 。 此 时 ， 我 们 不 再 需要 调用 
slashO0， 而 是 调用 linkTo0， 并 将 控制 右 中 的 一 个 方法 传递 给 它 ， 这 样 
ControllerLinkBuilder 吏 能 推 新 出 控制 名 的 基础 路 径 和 该 方法 的 映射 路 
径 。 如 下 的 代码 束 以 这 种 方式 使 用 J 了 linkTo0 方 法 : 


Resources<Resource<Taco>> recentResources = Resources.wrap(tacos); 
recentResources.add( 


linkTo(methodon(DesignTacoController.class).recentTacos()) 
.withRel("recents")); 





在 这 里 ， 我 表态 导入 了 了 linkTo() 和 methodOn0) 方 法 (它们 都 来 目 
ControllerLinkBuilder) ， 从 而 让 代码 更 易于 阅读 。methodOn0 方 法 传 入 
控制 器 类 ， 从 而 允许 我 们 调用 recentTacos() 方 法 ， 这 个 调用 会 被 


ControllerLinkBuilder 拦 堆 ， 用 来 确定 控制 器 的 基础 路 径 和 recentTacos() 
的 映射 路 径 。 现 在 ， 整 个 URL 都 从 控制 右 的 映射 中 判断 出 来 了 ， 而 且 完 
全 没有 便 编 码 。 非 钊 棒 ! 


6.2.2 ”创建 唤 源 少 配 天 


现在 ， 我 们 需要 为 列表 中 的 taco 资 源 添 加 链接 。 有 种 方案 就 是 过 历 
Resources 对 象 中 所 携 审 的 每 个 Resource<Taco> 元 素 ， 为 它们 依次 添加 
Link。 但 是 ， 这 种 方式 有 点 过 于 枯燥 ， 在 需要 返回 taco 列 表 的 所 有 地 方 
都 需要 在 API 中 重复 循环 相关 的 代码 。 


我 们 需要 有 一 种 不 同 的 委 略 。 
对 于 列表 中 的 每 个 taco， 我 们 不 再 使 用 Resources.wrap() 来 创建 
Resource， 而 是 定义 一 个 将 Taco 对 象 转换 为 TacoResource 对 象 的 工具 


类 。TacoResource 对 象 与 Taco 类 似 ， 但 是 它 本 身 能 携带 链接 。 程 序 清单 
6.5 展 示 了 TacoResource。 


程序 清单 6.5 ”能 够 携 市 领域 数据 和 超 链 接 列 表 taco 资 源 





package tacos.web.api; 

import java.util.Date,; 

import JjJava.util.List,; 

import org.springframework.hateoas.ResourceSupport, 
import lombok.Getter; 

import tacos.Ingredient,; 

import tacos.Taco; 


public class TacoResource extends ResourceSupport { 


QGetter 


private final String name ; 


QGetter 
private final Date createdAt; 


QGetter 
private final List<Ingredient> ingredients; 


public 
this 
this 
this 
} 


TacoResource(Taco taco) { 

.name = 上 aco.getName( ) ; 

.CreatedAt = taco.getCreatedAt( ) ; 
.ingredients = taco.getIngredients() ; 





从 很 多 方面 来 看 ，TacoResource 痢 与 Taco 领 域 类 型 没有 区 别 。 它 们 
部 有 name、createdAt 和 ingredients 属 性 。 但 是 ，TacoResource 扩 展 了 
ResourceSupport， 从 而 继承 了 一 个 Link 对 象 的 列表 和 管理 链接 列表 的 方 


法 。 


除 此 之 外 ，TacoResource 并 没有 包含 Taco 的 id 属性 。 这 是 因为 没有 
必要 在 API 中 暴露 数据 库 相 关 的 ID。 从 API 客 户 端的 角度 来 看 ， 资 源 的 
self 链 接 将 会 作为 该 资源 的 标识 付 。 


注意 : “领域 ?和 “资源 "应 该 各 目 独 立 还 是 应 该 是 同一 个 次 
呢 ? 有 些 Spring 开 友人 员 可 能 会 让 领域 类 型 扩展 
ResourceSupport， 从 而 将 领域 和 资源 对 象 合 二 为 一 。 全 于 哪 种 方 


式 才 是 正确 的 ， 这 里 并 没有 确切 谷 采 。 我 选择 的 做 法 是 创建 一 个 
单独 的 资源 类 型 ， 这 样 Taco 束 没有 必要 添加 资源 链 接 了， 因为 在 
有 些 场 景 下 ， 这 些 链 接 是 根本 用 不 到 的 。 力 外 ， 通 过 创建 一 个 时 





独 的 资源 类 型 ， 能 够 很 容易 地 将 id 属性 排除 出 去 ， 这 样 它 就 不 会 
暴露 在 API 中 了 。 





TacoResource 有 一 个 很 简单 的 构造 器 ， 会 接收 一 个 Taco 对 象 并 且 会 
将 Taco 中 的 相关 属性 复制 到 目 己 的 属性 中 。 这 样 的 话 ， 我 们 可 以 很 容 多 
地 将 一 个 Taco 对 象 转换 为 TacoResource。 但 是 ， 如 果 我 们 束 此 止步 ， 整 
依然 需要 授 历 Taco 列 表 才 能 将 其 转换 成 Resources<TacoResource>。 


为 了 将 Taco 对 象 转换 成 TacoResource 对 象 ， 我 们 需要 创建 一 个 资源 
装配 需 (resource assembler) 。 我 们 所 需要 的 闭 配 器 如 程序 清单 6.6 所 
不 。 





程序 清单 6.6 ”装配 taco 资 源 的 资源 装配 器 


package tacos.web.api; 
import org.springframework.hateoas.mvc.ResourceAssemblerSupport, 
import tacos.Taco; 


public class TacoResourceAssembler 
extends ResourceAssemblerSupport<Taco, TacoResource> { 


public TacoResourceAssembler() { 
super(DesignTacoController.class, TacoResource.class); 


} 


QOverride 
protected TacoResource instantiateResource(Taco taco) { 
return new TacoResource(taco); 


} 


QOverride 
public TacoResource toResource(Taco taco) { 
return createResourceWithId(taco.getId(), taco); 


TacoResourceAssembler 有 一 个 默认 的 构造 右 ， 会 告诉 超 类 
(ResourceAssemblerSupport) 在 创建 TacoResource 中 的 链接 时 将 会 使 用 
DesignTacoController 来 确定 所 有 URE 的 基础 路 径 。 


instantiateResource() 方 法 进行 了 音 写 ， 以 便 基于 给 定 的 Taco 实 例 化 
TacoResource。 如果 TacoResource 有 默认 构造 嚣 ， 那 么 这 个 方法 是 可 选 
的 。 但 是 ， 在 本 例 中 ，TacoResource 的 构造 过 程 需 要 Taco， 所 以 我 们 要 
章 写 它 。 


最 后 是 toResource(0) 方 法 ， 这 是 在 扩展 ResourceAssemblerSupport 时 
唯一 强制 实现 的 方法 。 在 这 里 ， 我 们 告诉 它 要 通过 Taco 创 建 
TacoResource， 并 且 有 要 设置 一 个 self 链 接 ， 这 个 链接 的 URL 是 根据 Taco 对 
象 的 id 属 性 衍生 出 来 的 。 


在 表面 上 ，toResource() 和 instantiateResource() 的 用 途 很 相似 ， 但 是 
它们 的 目的 略 有 不 同 。instantiateResourceO 只 是 为 了 实例 化 一 个 
Resource 对 象 ， 而 toResource() 的 意图 不 仪 是 创建 Resource 对 象 ， 还 要 为 
其 填充 链接 。 在 内 部 ，toResource() 将 会 调用 instantiateResource()。 


现在 ， 我 们 调整 一 下 recentTacos()， 让 它 使 用 


TacoResourceAssembler: 





@GetMapping("/recent") 
public Resources<TacoResource> recentTacos() { 
PageRequest page = PageRequest.of( 


0, 12, Sort.by("createdAt").descending()); 
List<Taco> tacos = tacoRepo.findAll(page).getContent(); 


List<TacoResource> tacoResources = 
new TacoResourceAssembler().toResources(tacos); 
Resources<TacoResource> recentResources = 
new Resources<TacoResource>(tacoResources ) ; 
recentResources.add( 
linkTo(methodOon(DesignTacoController.class).recentTacos()) 
.withRel("recents")); 
return recentResources,; 





在 这 里 ，recentTacos() 的 返回 值 不 再 是 Resources<Resource<Taco>> 
类 型 ， 而 是 利用 我 们 新 定义 的 TacoResource 类 型 返回 了 一 个 
Resources<TacoResource>。 在 从 repository 获 取 taco 之 后 ， 我 们 将 Taco 对 
象 的 列表 传递 给 TacoResourceAssembler 的 toResources() 方 法 。 这 个 便利 
的 方法 会 循环 所 有 的 Taco 对 象 ， 调 用 我 们 在 TacoResourceAssembler 中 重 
写 的 toResource0) 方 法 来 创建 TacoResource 对 象 的 列表 。 


在 有 了 TacoResource 列 表 之 后 ， 我 们 接 下 来 创建 了 
Resources<TacoResource> 对 象 ， 人 然后 像 有 前面 版 本 的 recentTacos() 一 样 ， 
为 其 填充 了 recents 链 接 。 


此 时 ， 对 “/design/recent” 发 起 GET 请 求 将 会 生成 taco 的 一 个 列表 ， 其 
中 的 每 个 taco 都 有 一 个 self 链 接 ， 而 列表 整体 有 一 个 recents 链 接 。 但 是 ， 
配料 目前 还 没有 链接 。 为 了 解决 这 个 问题 ， 我 们 需要 为 配料 创建 一 个 新 
的 资源 闻 配 天 





package tacos.web.api; 
import org.springframework.hateoas.mvc.ResourceAssemblerSupport,; 
import tacos.Ingredient,; 


class IngredientResourceAssembler extends 
ResourceAssemblerSupport<Ingredient, IngredientResource> 1{ 


public IngredientResourceAssembler() { 
super(IngredientController2.class, IngredientResource.class); 


} 


QOverride 
public IngredientResource toResource(Ingredient ingredient) { 
return createResourceWithId(ingredient.getId(), ingredient); 


} 


QOverride 
protected IngredientResource instantiateResourcel( 
Ingredient ingredient) { 
return new IngredientResource(ingredient); 


} 


我 们 可 以 看 到 ，IngredientResourceAssembler 与 
TacoResourceAssembler 非 党 相似 ， 但 是 它 使 用 的 是 Ingredient 和 和 
IngredientResource 对 象 而 不 是 Taco 和 TacoResource 对 象 。 


谈 到 IngredientResource 对 象 ， 它 的 源码 如 下 所 示 : 





package tacos.web.api; 

import org.spriIngframework.hateoas .ReSsourceSupport ; 
Import Lombok .Getter ; 

import tacos.Ingredient,; 

import tacos.Ingredient.Type; 


public class IngredientResource extends ResourceSupport 1{ 


QGetter 
private String name; 


QGetter 
private Type type; 


public IngredientResource(Ingredient ingredient) { 
this.name = ingredient.getName(); 
this.type = ingredient.getType() ; 


与 TacoResource 类 似 ，IngredientResource 扩 展 了 ResourceSupport， 
并 且 会 将 领域 类 型 相关 的 属性 复制 到 目 己 的 属性 中 (id 属性 际 外 )。 


接 下 来 ， 我 们 需要 修改 一 下 TacoResource， 让 它 能 够 携 禹 
IngredientResource 对 象 ， 而 不 是 mgredient 对 象 : 


package tacos.web.api; 

Import java.util.Date; 

import JjJava.util.List,; 

import org.springframework.hateoas.ResourceSupport,; 
Import lombok.Getter; 

import tacos.Taco; 


public class TacoResource extends ResourceSupport { 


private static final IngredientResourceAssembler 
ingredientAssembler = new IngredientResourceAssembler(); 


QGetter 
private final String name; 


QGetter 
private final Date createdAt ; 


QGetter 
private final List<IngredientResource> ingredients; 


public TacoResource(Taco taco) { 
this.name = taco.getName() ; 
this.createdAt = taco.getCreatedAt( ) ; 
this.ingredients = 
ingredientAssembler.toResources(taco.getIngredients() ) ; 





这 个 新 版 本 的 TacoResource 会 创建 一 个 static final 的 


IngredientResourceAssembler 实 例 ， 并 且 会 使 用 它 的 toResource() 方 法 将 
给 定 Taco 对 象 的 Ingredient 列 表 转 换 成 IngredientResource 列 表 。 


我 们 现在 的 taco 列 表 已 经 完全 具备 了 超 链接 ， 不 仅 是 它 本 丑 
(recents 链 接 ) ， 而 且 所 有 的 taco 条 目 和 每 个 taco 中 的 配料 都 有 了 超 链 
接 。 啊 应 的 内 容 应 该 与 程序 清早 6.3 非 党 相似 了 了。 


你 可 以 驶 此 止步 并 跳 到 下 一 下 ， 但 是 在 此 之 前 ， 我 想 解 决 程序 清单 
6.3 中 一 些 不 太 理 想 的 问题 。 


6.2.3 ”全 名 藤 侠 式 的 关联 天 系 


如 果 你 仔细 看 一 下 程序 清单 6.3， 束 会 发 现 顶层 的 元 素 如 下 所 示 : 


{ 


”embedded : { 
"tacoResourcelList": | 





最 值得 注意 的 是 在 embedded 之 下 有 一 个 名 为 tacoResourceList 的 属 
性 。 之 所 以 有 这 个 名 称 ， 征 因为 Resources 对 象 是 通过 
List<TacoResource> 创 建 出 来 的 。 尽 管 可 能 性 不 太 大 ， 但 是 假 议 我 们 将 
TacoResource 关 重 构 成 了 其 他 的 名 称 ， 那 么 结束 JSON 中 的 字段 名 将 会 随 
之 及 生变 化 。 这 样 ， 所 有 依赖 该 名 称 的 客户 交代 但 都 会 产生 问题 。 


Q@Relation 注 解 能 够 帮助 我 们 消除 JSON 字 段 名 和 Java 代 但 中 定义 的 


资源 类 名 之 间 的 耦合 。 通 过 为 TacoResource 汪 加 @Relation 注 解 ， 我 们 惑 
能 指定 Spring HATEOAS 访 如何 命 名 结果 JSON 中 的 字段 名 : 


@Relation(value="taco", collectionRelation="tacos") 
public class TacoResource extends ResourceSupport { 





} 


在 这 里 ， 我 们 指定 当 在 Resources 对 象 中 引用 TacoResource 对 象 列表 
时 它 应 该 被 命名 为 tacos。 虽 然 在 我 们 的 API 中 没有 用 到 ， 但 是 如 末 在 
JSON 中 引用 单个 TacoResource 对 象 ， 那 么 它 的 名 字 将 会 是 taco。 这 样 的 
话 ，“/design/recent" 所 返回 的 JSON 将 会 如 下 所 示 “不管 我 们 是 否 要 对 
TacoResource 进 行 重 构 ， 这 个 结构 都 不 会 发 生变 化 ) : 


”embedded : { 
"tacos": | 





借助 Spring HATEOAS， 癌 API 中 添加 链接 变 得 非 间 简单 直接 。 尽 管 
如 此 ， 它 也 会 添加 一 些 额 外 的 代码 。 所 以 ， 很 多 开发 人 员 会 选择 在 API 
中 不 使 用 HATEOAS， 但 是 如 果 API 的 URL 模 式 发 生变 化 ， 那 么 客户 端 
代码 残 不 可 用 了 。 上 所 以 ， 我 建议 你 认真 考虑 一 下 HATEOAS， 不 要 因为 
偷懒 而 急 略 在 资源 中 添加 超 链 接 。 


如 果 你 真 的 想 要 偷懒 ， 那 么 只 要 你 使 用 Spring Data 来 实现 
repository， 我 们 就 还 有 一 个 双 瓦 的 方案 。 接 下 来 ， 我 们 看 一 下 基于 在 第 
3 草 中 使 用 Spring Data 所 创建 的 数据 repository， 如 何 信和 助 Spring Data 


REST 目 动 创 建 API。 


6.3 ”局 用 数据 后 闹 服 务 


正如 我 们 在 第 3 章 中 所 看 到 的 ，Spring Data 有 一 种 特殊 的 魔法 ， 它 
能 够 基于 我 们 定义 的 接口 自动 创建 repository 实 现 。 但 是 Spring Data 还 有 
另外 一 项 技巧 ， 它 能 帮助 我 们 定义 应 用 的 API。 


Spring Data REST 是 Spring Data 家 族 中 的 另外 一 个 成 员 ， 它 会 为 
Spring Data 创 建 的 repository 目 动 生成 REST API。 我 们 只 需要 将 Spring 
Data REST 汶 加 到 构建 文件 中 ， 残 能 得 到 一 套 API， 筷 的 操作 与 我 们 定义 
repository 接 口 是 一 致 的 。 


为 了 使 用 Spring Data REST， 我 们 需要 将 如 下 的 依赖 浴 加 到 构建 文 
人 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-data-rest</artifactId> 
</dependency> 





不 管 你 是 否 相 信 ， 对 于 已 经 使 用 Spring Data 目 动 生成 repository 的 项 
目 来 说 ， 我 们 只 需要 完成 这 一 步 克 能 对 外 姑 露 REST API 了 了 。 将 Spring 
Data REST starter 浴 加 到 构建 文件 中 之 后 ， 应 用 的 目 动 配置 功能 会 为 
Spring Data (包括 Spring Data JPA、Spring Data Mongo 等 ) 创建 的 所 有 
repository 目 动 创建 REST API。 


Spring Data REST 所 创建 的 端点 和 我 们 目 己 创建 的 闹 点 一样 好 【其 


至 能 够 更 好 一 些 ) 。 所 以 ， 我 们 可 以 做 一 些 移 除 操作 ， 在 进行 下 一 步 之 
前 将 我 们 已 经 创建 的 市 有 @RestController 注 解 的 类 移 除 。 


为 了 符 试 Spring Data REST 握 供 的 姗 点， 我 们 可 以 司 动 应 用 并 训 试 
一 些 URL。 基 于 为 Taco Cloud 定 义 的 repository， 我 们 可 以 对 taco、 配 
料 、 订 单 和 用 户 执行 一 些 GET 请 求 。 


举例 来 说 ， 我 们 可 以 同 “Vingredients” 发 送 GET 请 求 以 获取 所 有 配 
料 。 借 助 curl， 我 们 得 到 的 啊 应 大 至 如 下 所 示 (进行 了 删 减 ， 只 显示 第 
一 种 配料 ) s 


$ curl localhost:806806/ingredients 
{ 
" embedded" : { 
"ingredients" : | 1{ 
"name” : "Flour Tortilla", 
"”: "WRAP", 


" : "http://localhost:8060806/ingredients/FLTO" 


"ingredient™" : { 
"href” : "http://localhost:806806/ingredients/FLTO" 


”2: "http://localhost:8060806/ingredients" 


: 4 
"href” : "http://localhost:8060806/profile/ingredients" 





太 棒 了 ! 我 们 只 不 过 将 一 项 依赖 添加 到 了 构建 文件 中 ， 这 样 不 但 得 
到 了 针对 配料 的 端点 ， 而 且 返 回 的 资源 中 还 包含 超 链接 。 我 们 可 以 假装 
成 这 个 API 的 客户 端 ， 使 用 cunl 继 续 访问 self 链 接 以 获取 玉米 面 薄饼 的 详 


$ curl http://localhost:8060806/ingredients/FLTO 
{ 
"name”" : "Flour Tortilla", 

[a "WRAP”" 


" : "http://localhost:8060806/ingredients/FLTO" 


"ingredient" : { 
"href” : "http://localhost:806806/ingredients/FLTO" 





为 了 避免 分 黎 注 意 力 ， 在 本 书 中 ， 我 们 不 再 浪费 时 间 深 入 探 完 
Spring Data REST 所 创建 的 每 个 问 点 和 可 选项 。 但 是 ， 我 们 需要 知道 ， 
它 还 支持 端点 的 POST、PUT 和 DELETE 方 法 。 也 就 是 说 ， 你 可 以 发 送 
POST 请 求全 “/ingredients” 来 创建 狐 的 配料 ， 也 可 以 发 送 DELETE 请 求 
人 到“/ingredients/FLTO”， 以 便于 从 六 蛙 中 删除 玉米 面 注 人 饼 。 


我 们 想 做 的 男 外 一 件 事 可 能 束 是 为 API 设 置 一 个 基础 路 任 ， 这 样 它 
们 会 有 不 同 的 靖 点 ， 避 免 与 我 们 所 编 与 的 控制 夯 产 生 剖 突 《〈 实 际 上 ， 如 
果 我 们 不 删除 前 面 自己 创建 的 IngredientsController， 就 将 会 干扰 Spring 
Data REST 提 供 的 “ingredients” 站 点 ) 。 为 了 调整 API 的 基础 路 径 ， 我 们 
可 以 设置 spring.data.rest.base-path 属 性 : 


spring: | 


data: 
rest: 
base-path: /api 
这 项 配置 会 将 Spring Data REST 病 点 的 基础 路 任 设 置 为 “/api”。 现 
在 ， 配 料 端 点 将 会 变 成 %apiingredients”。 我 们 通过 请 求 taco 列 表 来 验证 
一 下 这 个 新 的 基础 路 径 : 


$ curl http://localhost:8060806/api/tacos 
{ 


"timestamp": “2018-02-11T16:22:12.381+0066  ， 
"status": 4064, 

"error": "Not Found", 

"message": "No message available'",， 

"path": "/api/tacos" 





哦 ， 天 啊 ! 它 并 没有 按照 预期 那样 运行 。 我 们 有 了 Ingredient 实 体 和 
IngredientRepository 接 口 之 后 ，Spring Data REST 束 会 暴 
露 “/api/ingredients”。 我 们 也 有 Taco 实 体 和 TacoRepository 接 口 ， 为 什么 
Spring Data REST 没 有 为 我 们 生成 “/api/tacos” 闹 点 呢 ? 


6.3.1 调整 资源 路 人 径 和 关系 名 称 


实际 上 ，Spring Data 确 实 为 我 们 提供 了 处 理 taco 的 端点 。 昌 然 Spring 
Data REST 非 常 聪明 ， 但 是 在 又 圳 taco 闹 点 的 时 候 出 现 了 一 点 问题 。 


当 为 Spring Data repository 创 建 端 点 的 时 候 ，Spring Data REST 会 党 
试 使 用 相关 实体 类 的 复数 形式 。 对 于 Ingredient 实 体 来 说 ， 新 丘 将 会 
是 “/ingredients”， 对 于 Order 和 User 实 体 ， 病 点 将 会 


征 “/orders” 和 ”users”。 到 目前 为 止 ， 一 切 运行 展 好 。 但 有 些 场景 下 ， 比 
如 过 到 “taco” 的 时 候 ， 它 获取 到 这 个 单词 ， 为 其 生成 的 复数 形式 束 不 太 
下 确 了 。 实 际 上 ，Spring Data REST 将 “taco” 的 复数 形式 计算 成 

了 “tacoes"”， 所 以 ， 为 了 回 taco 肥 这 请 求 ， 我 们 必 朋 将 铺 束 销 ， 请 

求 “/api/tacoes” 地 址 : 


%» curl localhost:806806/api/tacoes 


" embedded" : { 
"tacoes” : | 1 
"name” : "Carnivore", 
"createdAt” : "206018-62-11T17:061:32.999+6060060"， 


": "http://localhost:8060806/api/tacoes/2" 


": "http://localhost:8060806/api/tacoes/2" 


"ingredients™” : 1{ 
"href” : "http://localhost:8060806/api/tacoes/2/ingredients" 


"totalElements” : 3， 
"totalPpages"” : 1, 





你 肯定 会 想 ， 我 是 怎么 知道 “taco” 的 复数 形式 被 错误 计算 成 
了 “tacoes”。 实 际 上 ，Spring Data REST 还 暴露 了 一 个 主 资源 (home 
resource) ， 这 个 资源 包含 了 所 有 交点 的 链接 。 我 们 只 需要 回 API 的 基础 
路 径 及 达 GET 请 求 殴 能 得 到 它 的 结 末 : 


$ curl localhost:8086/api 


" links” : { 
"orders™" : 1{ 
"href” : "http://localhost:8060806/api/orders" 
}, 
"ingredients™” : 1{ 
"href” : "http://localhost:8060806/api/ingredients" 
}, 
"tacoes” : 1{ 
“href”: "http://localhost:806806/api/tacoes{?page,size,sort}",， 
"templated”" : true 
}, 
"users” : { 
"href” : "http://localhost:80608060/api/users" 
}, 
"profile™ : { 
"href” : "http://localhost:8060806/api/profile" 
} 
} 


} 


可 以 看 到 ， 这 个 主 资源 显示 了 所 有 实体 的 链接 。 除 了 tacoes 链 接 之 
外 ， 其 他 都 很 好 ， 在 这 里 关系 名 和 URL 地 址 上 都 是 “taco” 错 误 的 复数 形 
式 。 


好 消息 是 ， 我 们 并 非 必 须 接受 Spring Data REST 的 这 个 小 错误 。 通 
过 为 Taco 深 加 一 个 简单 的 注解 ， 我 们 束 能 调整 天 系 名 和 路 径 : 


@Data 

@EnNtity 

@RestResource(rel="tacos", path="tacos") 
public class Taco 1{ 


ee 





@RestResource 注 解 能 够 为 实体 提供 任何 我 们 想 要 的 关系 名 和 路 
径 。 在 本 例 中 ， 我 们 将 它们 都 设置 成 了 “tacos”。 现 在 ， 我 们 请 求 主 资源 


的 时 候 ， 会 看 到 tacos 有 了 正确 的 复数 形式 : 


"七 cos” : { 
“href”: "http://localhost:806806/api/tacos{?page,size,sort}", 


"templated”" : true 
}, 





这 样 束 将 我 们 的 端点 路 径 整 理 好 了 ， 现 在 可 以 同 %api/tacos” 发 送 请 
求 来 操作 taco 资 源 了 。 


接 下 来 我 们 看 一 下 使 用 Spring Data REST 端 点 如 何 进 行 排序 。 
6.3.2 分 页 和 排 友 


你 可 能 已 经 发 现 ， 主 资源 上 的 所 有 链接 都 提供 了 可 选 的 page、size 
和 sort 参 数 。 默 认 情 况 下 ， 请 求 集合 资源 (比如 “/api/tacos”) 都 会 返回 
第 一 页 的 20 个 条 有 目 。 但 是 ， 我 们 可 以 通过 在 请 求 中 指定 page 和 size 参 数 
调整 具体 的 页 数 和 每 页 的 数量 。 


例如 ， 我 们 想 要 请 求 第 一 页 的 taco， 但 是 希望 包含 5 个 条 目 ， 束 可 以 
及 大 如 下 的 GET 请 求 〈 使 用 curl) : 


$ curl "localhost :8686/api/tacos?size=5" 


如 果 taco 的 数量 超过 了 5 个 ， 我 们 可 以 通过 使 用 page 参 数 获取 第 二 页 
的 taco: 


$ curl "localhost :8686/api/tacos?size=5&page=1" 





注 量 ，page 参 数 是 从 0 开始 计算 的 ， 也 束 是 说 page 值 为 1 的 时 候 会 请 
求 第 二 页 的 数据 (你 可 能 会 发 现 ， 很 多 命令 行 shell 过 到 请 求 中 的 以 从 号 
会 出 错 ， 所 以 我 们 在 前 面 的 curl 命 令 中 为 整个 URL 使 用 了 引号 ) 。 


我 们 可 以 使 用 字符 串 操 作 来 将 这 些 参 数 拼接 到 URL 上， 但 是 
HATEOAS 为 我 们 提供 了 第 一 页 、 下 一 页 、 上 一 页 和 最 后 一 页 等 链接 : 


"http://localhost:806806/api/tacos?page=06&size=5" 
“http:// Localhost :8686/apI/tacos 
"http://localhost:806806/api/tacos?page=1&size=5" 


"http://localhost:806806/api/tacos?page=2&size=5" 


"profile™ : 1{ 

"href” : "http://localhost:8060806/api/profile/tacos" 
}, 
"recents™” : {1{ 

"href” : "http://localhost:8060806/api/tacos/recent”" 


} 


} 





有 了 这 些 链 接 ，API 的 客户 闹 束 不 需要 跟 躁 当前 正 处 于 哪 一 页 ， 世 
不 用 将 参数 目 己 拼接 到 URL 上 了 ， 只 需 根据 名 字 奏 找 这 些 页 面 导 航 并 进 
行 访问 束 可 以 了 。 


Sort 参数 允 许 我 们 根据 实体 的 茶 个 属性 对 结果 进行 排序 。 例 如 ， 我 
们 想 要 获取 最 近 创 建 的 12 条 taco 进 行 UI 展 示 ， 束 可 以 混合 使 用 分 页 和 排 
序 参 数 实现 : 





$ curl "localhost :8686/api/tacos?sort=createdAt ,desc&page=6&slize=12" 


在 这 里 ，sort 参 数 指定 我 们 要 按照 createdAt 属 性 进行 排序 ， 并 且 要 
按照 降序 进行 排列 〈 所 以 最 新 的 taco 会 放 在 最 前 面 ) 。page 和 Size 参数 指 
定 我 们 想 要 获取 第 一 页 的 12 个 taco。 


这 恰好 是 UI 展现 最 近 创 建 的 taco 有 所 需要 的 数据 。 它 与 我 们 在 本 章 前 
文 DesignTaco Controller 定 义 的 “/design/recent” 闹 点 大 八 相 同 。 


这 里 还 有 一 个 小 回 题 。UI 代 码 需 要 便 编 码 才 能 请 求 市 有 指定 参数 的 
taco 列 表 。 当 然 ， 这 可 以 正 彰 运行。 但 是 ， 如 果 让 客户 站 太 多 地 了 解 如 
何 构建 API 请 求 ， 束 会 在 一 定 程 度 上 增加 脆弱 性 。 如 果 客 户 疹 能 够 从 链 
接 列 表 中 得 找 URL 了 吏 太 好 了 。 如 果 URL 能 够 更 答 洁 ， 残 像 前 面 看 
到 “design/recent” 一 样 ， 那 束 更 棒 了 了 。 


6.3.3 ”添加 目 定 义 的 病 操 


Spring Data REST 能 够 很 好 地 为 执行 CRUD 操 作 的 Spring Data 
repository 创 建 训 点 。 但 有 时 候 ， 我 们 需要 及 离 默 认 的 CRUD API， 创 建 
处 理 核心 问题 的 端点 。 


我 们 当然 可 以 在 带 有 Q@RestController 注 解 的 bean 中 实现 任意 的 妆 
反 ， 以 此 来 补充 Spring Data REST 奖 点 的 不 足 。 实 际 上 ， 我 们 可 以 重新 
司 用 本 章 前 面 提 到 的 DesignTacoController， 它 依然 可 以 与 Spring Data 
REST 皖 供 的 咒 氮 一 起 运行 。 


但 是 在 编号 目 己 的 API 控 制 项 时 ， 它 们 的 奖 点 在 有 些 方面 会 与 
Spring Data REST 的 闹 点 脱节 : 


。 我 们 目 己 的 控制 器 端点 没有 映射 到 Spring Data REST 的 基础 路 猎 
下 。 虽 然 我 们 可 以 强制 要 求 它们 映 冉 到 任意 前 级 作为 基础 路 和 任 ， 包 
括 使 用 Spring Data REST 的 基础 路 人 笃 ， 但 是 如 末 基 础 路 人 笃 发 生变 化 
的 话 ， 我 们 还 需要 修改 控制 右 的 映射 ， 以 便于 与 其 匹配 。 
。 在 目 己 控制 硕 所 定义 的 奖 点 中 ， 返 回 资源 时 并 不 会 目 动 包含 超 链 
接 ， 与 Spring Data REST 所 返回 的 资源 是 不 同 的 。 这 意味 着 ， 客 户 
站 无 法 通过 关系 名 发 现 目 定 义 的 奖 点 。 
我 们 首先 来 解决 基础 路 径 的 问题 。Spring Data REST 提 供 了 一 个 新 
的 注解 @RepositoryRestController， 这 个 注解 可 以 用 到 控制 硕 闫 上， 这 样 
控制 器 类 所 有 映射 的 基础 路 径 就 会 与 Spring Data REST 端 点 配置 的 基础 
路 径 相 同 。 简 而 言 之 ， 在 使 用 @RepositoryRestController 注 解 的 控制 器 
中 ， 所 有 映射 将 会 具有 和 spring.data.rest.base-path 属 性 值 一 样 的 前 级 (我 
们 之 前 将 这 个 属性 的 值 配 置 成 了 “api”) 。 


在 这 里 我 们 会 创建 一 个 只 包含 recentTacos0) 方 法 的 新 控制 器 ， 而 不 
古 修改 已 有 的 DesignTacoController， 因 为 这 个 旧 的 控制 器 包含 了 多 个 我 
们 不 再 需要 的 方法 。 程 序 清 单 6.7 中 的 RecentTacosController 市 有 
@RepositoryRestController 注 和 解 ， 表 明 筷 会 将 Spring Data REST 的 基础 路 
径 用 到 目 己 的 请 求 映 射 上 。 


程序 清单 6.7 将 Spring Data REST 的 基础 路 径 用 到 控制 器 上 





package tacos.web.api; 
Import static org.springframework.hateoas.mvc.ControllerLinkBuilder.*; 


Import java.util.List; 

import org.springframework.data.domain.PageRequest, 

import org.springframework.data.domain.Sort,; 

import org.springframework.data.rest.webmvc.RepositoryRestController; 
import org.springframework.hateoas.Resources; 

import org.springframework.http.HttpStatus; 

import org.springframework.http.ResponseEntity; 

import org.springframework.web.bind.annotation.GetMapping; 

import tacos.Taco; 

Import tacos.data.TacoRepository; 


QRepositoryRestController 
public class RecentTacosController { 


private TacoRepository tacoRepo; 


public RecentTacosController(TacoRepository tacoRepo) { 
this.tacoRepo = tacoRepo,; 


} 


@GetMapping(path="/tacos/recent", produces="application/hal+json") 
public ResponseEntity<Resources<TacoResource>> recentTacos() { 
PageRequest page = PageRequest.of( 
806, 12, Sort.by("createdAt").descending()); 
List<Taco> tacos = tacoRepo.findAll(page).getContent(); 


List<TacoResource> tacoResources = 
new TacoResourceAssembler().toResources(tacos); 
Resources<TacoResource> recentResources = 
new Resources<TacoResource>(tacoResources ) ; 
recentResources.add( 
linkTo(methodOon(RecentTacosController.class).recentTacos()) 
.withRel("recents")); 
return new ResponseEntity<>(recentResources, HttpStatus.OkK); 


虽然 @GetMapping 映 射 到 了 “tacos/recent” 路 径 ， 但 是 类 级 别 的 
(@Repository RestController 注 解 会 确保 这 个 路 径 深 加 Spring Data REST 的 
基础 路 径 作 为 前 缀 。 按 照 我 们 的 配置 ，recentTacos0) 方 法 将 会 处 理 针 
对 “/api/tacos/recent” 的 GET 请 求 。 


需要 注 晶 的 是 ， 尽 管 @RepositoryRestController 的 名 称 和 
@RestController 非 党 相似 ， 但 是 它 并 没有 和 人 @RestController 相 同 的 语 
义 。 有 具体 来 讲 ， 它 并 不 能 保证 处 理 需 方法 返回 的 值 会 目 动 号 入 啊 应 体 
中 。 所 以 ， 我 们 要 么 为 方法 添加 @ResponseBody 注 解 ， 要 么 返回 包装 啊 
应 数据 的 ResponseEntity。 这 里 我 们 选择 的 方案 是 返回 ResponseEntity。 


RecentTacosController; 侍 备 吏 绪 之 后 ， 对 “api/tacos/recent” 肥 大 请 求 
最 多 会 运 回 15 条 最 近 创 建 的 taco， 此 时 束 不 需要 在 URL 中 添加 分 页 和 排 
序 参 数 了。 但 是 在 请 求 “/api/tacos” 的 时 候 ， 这 个 地 址 依然 没有 出 现在 结 
条 的 超 链接 列表 中 。 


6.3.4 ”为 Spring Data 痪 点 添加 目 定 义 的 超 链 接 


如 果 最 近 taco 端 点 没有 出 现在 %api/tacos” 所 返回 的 超 链 接 中 ， 那 么 
客户 端 如 何 知道 该 怎样 获取 最 近 的 taco 呢 ? 它 要 么 猜测 ， 要 么 使 用 分 页 
和 排序 参数 。 无 论 采 用 哪 种 方式 ， 痢 再 要 在 客户 冰 代 码 中 便 编 权 ， 这 都 
不 是 理想 的 做 法 。 


通过 丽 明 资源 处 理 磊 (resource processor) bean， 我 们 可 以 为 Spring 
Data REST 上 自动 包含 的 链接 列表 继续 添加 链接 。Spring Data HATEOAS 
提供 了 一 个 ResourceProcessor 接 口 ， 能 够 在 资源 通过 API 返 回 之 前 对 其 
进行 操作 。 对 于 我 们 的 场景 来 说 ， 需 要 一 个 ResourceProcessor 实现 ， 为 
PagedResources<Resource<Taco>> 关 型 的 资源 《也 殉 是 “api/tacos” 疹 氮 


所 返回 的 次 型 ) 添加 recents 链 接 。 程 序 清单 6.8 展 现 了 定义 这 种 


ResourceProcessor 的 bean 声 明 方 法 。 
程序 清单 6.8 ”为 Spring Data REST 冰 点 添加 目 定 义 的 链接 


QBean 
public ResourceProcessor<PagedResources<Resource<Taco>>> 
tacoProcessor(EntityLinks links) { 


return new ResourceProcessor<PagedResources<Resource<Taco>>>() { 
QOverride 
public PagedResources<Resource<Taco>> process( 
PagedResources<Resource<Taco>> resource) { 


resource.add( 
links.1linkFor(Taco.class) 
.Slash("recent") 
.withRel("recents")); 
return resource, 


} 
上 


} 





程序 清单 6.8 中 的 ResourceProcessor 定 义 了 一 个 匿名 内 部 类 ， 并 将 其 
声 明 为 Spring 应 用 上 下 文中 所 创建 的 bean。Spring HATEOAS 会 自动 友 现 
这 个 bean (以 及 其 他 ResourceProcessor 类 型 的 bean) 并 将 其 应 用 到 对 应 
的 资源 上 。 在 本 例 中 ， 如 未 控制 花 返 回 
PagedResources<Resource<Taco>>， 了 吏 会 包含 一 个 最 近 创 建 的 taco 链 接 。 
这 束 包 括 了 对 “/api/tacos” 请 求 的 啊 应 。 


6.4 ”小 结 


。 REST 端 点 可 以 通过 Spring MVC 来 创建 ， 这 里 的 控制 器 与 面向 浏览 
镶 有 的 控制 器 杀人 循 相同 的 编程 模型 。 

。 为 了 绕 过 视图 和 模型 的 迎 辑 并 将 数据 和 朋 接 写 入 啊 应 体 中 ， 控 制 右 处 
理 方 法 既 可 以 添加 @ResponseBody 注 解 也 可 以 返回 ResponseEntity 对 


象 。 

e。 (@DRestController 注 解 简 化 了 REST 控 制 占 ， 使 用 它 的 话 ， 人 处 理 器 方 
法 中 就 不 需要 添加 @ResponseBody 注 解 了 。 

。 Spring HATEOAS 为 Spring MVC 控 制 占 返回 的 资源 启用 了 超 链 接 功 
能 。 

。 信 助 Spring Data REST，Spring Data repository 可 以 目 动 导出 为 REST 
APl。 





[1] 在 这 里 ， 我 选择 使 用 Angular， 但 是 前 并 框架 的 选择 应 该 对 后 妆 
Spring 代 人 码 的 编写 没有 影响 ， 所 以 你 尽 可 以 选择 Angular、React、Vue.js 
或 者 其 他 适合 你 的 前 问 技 术 。 


第 7 章 ”消费 REST 服 务 


。 使 用 RestTemplate 消 费 REST API 


e 使 用 Traverson 导 航 超 媒体 API 





你 有 没有 过 这 样 的 经 历 一 一 跑 去 看 电影 ， 却 友 现 目 己 是 影院 中 唯一 
的 一 个 人 。 这 当然 是 一 种 很 奇妙 的 经 历 ， 从 本 质 上 来 讲 ， 这 变 成 了 一 个 
私人 电影 。 你 可 以 选择 任意 想 要 的 座位 、 和 屏 需 上 的 角色 交谈 ， 长 至 可 
以 打开 手机 发 推 项 ， 完 全 不 用 担心 因为 破坏 了 列 人 的 观 影 体验 而 春 人 生 
气 。 最 棒 的 是 ， 没 有 人 会 毁 了 你 观看 这 部 电影 的 心情 。 

对 我 来 说 ， 这 样 的 事情 并 不 常见 。 但 是 ， 过 到 这 种 情况 的 时 候 ， 我 
会 想 ， 如 果 我 也 不 出 现 的 话 会 友 生 什么 呢 ? 工 作 人 员 还 会 播放 这 部 影 
吗 ? 电影 中 的 现 雄 还 会 拯救 世界 吗 ? 电影 播放 结束 后 ， 工 作 人 员 还 会 打 


扫 影 院 吗 ? 


疫 有 观众 的 电影 吏 像 没有 客户 站 的 API。 这 些 API 已 经 准备 好 接收 


和 提供 数据 了 ， 但 是 如 果 它 们 从 来 没有 被 调用 过 ， 它 们 还 是 API 吗 ? 整 
像 醉 定 调 的 猫 一 样 ， 在 发 起 请 求 之 前 ， 我 们 并 不 知道 这 个 API 是 否 活 
跃 ， 也 不 知道 它 是 售 返 回 HITP 404 啊 应 。 


在 表面 的 草 节 中， 我 们 主要 关注 如 何 定义 REST 靖 点， 它们 可 以 家 
应 用 外 部 的 客户 病 所 消费 。 尽 管 开 有 友 这 种 API 的 主要 张 动力 是 单 页 
Angular 恬 用， 以 便于 实现 Taco Cloud Web 站 点 ， 但 实际 上 客户 端 可 以 是 
任意 应 用 ， 可 以 是 任何 语言 ， 甚 全 可 以 是 另外 一 个 Java 心 用 。 


Spring 应 用 除了 提供 对 外 API 之 外 ， 同 时 要 对 另外 一 个 应 用 的 API 发 
起 请 求 的 场景 并 不 罕见 。 实 际 上 ， 在 微服 务 领域 ， 这 正 变 得 越 来 越 普 
通 。 因 此 ， 花 点 时 间 研 究 一 下 如 何 使 用 Spring 与 REST API 交 互 是 非常 值 
得 的 。 


Spring 应 用 可 以 采用 多 种 方式 来 消费 REST API， 包 括 以 下 几 种 方 
式 : 


RestTemplate: Spring 核 心 框架 提供 的 人 简单、 同步 REST 客 诱 并。 
Traverson: Spring HATEOAS 提 供 的 支持 超 链 接 、 同 步 的 REST 客 三 
闹 ， 其 灵感 来 源 于 同名 的 JavaScript 库 。 

。 WebClient: Spring 5 所 引入 的 反应 式 、 异 步 REST 客 户 病 。 


我 将 WebClient 推 运 到 第 11 间 讨论 Spring 的 反应 式 Web 框 染 时 再 进行 
介绍 ， 现 在 我 们 主要 关注 其 他 的 两 个 REST 客 户 端 。 下 面 先 从 
RestTemplate 开 始 。 


7.1 使 用 RestTemplate 消 费 REST 闪 操 


从 客户 器 的 角度 来 看 ， 与 REST 资 源 进 行 区 互 涉及 很 多 工作 ， 而 且 
大 多 数 都 是 很 单调 乏味 的 样板 式 代 码 。 如 果 使 用 较 低 层级 HITP 库 ， 客 
户 靖 融 需 要 创建 一 个 客户 病 实 例 和 请 求 对 象 、 执 行 请 求 、 解 析 啊 应 、 将 
啊 应 映射 为 领域 对 象 ， 并 且 还 要 处 理 这 个 过 程 中 可 能 会 抛 出 的 所 有 有 蜡 
单 。 不 管 及 送 什么 样 的 HITP 请 求 ， 这 种 样板 代码 都 要 不 断 重 复 。 


为 了 避免 这 种 样板 代码 ，Spring 提 供 了 RestTemplate。 就 像 
JDBCTemplate 能 够 处 理 JDBC 中 丑陋 的 那 部 分 代码 一 样 ，RestTemplate 
也 能 够 将 你 从 消费 REST 资 源 所 面临 的 单调 工作 中 解放 出 来 。 


RestTemplat 提 供 了 41 个 与 REST 资 源 交 互 的 方法 。 我 们 不 会 详细 介 
绍 它 所 提供 的 所 有 方法 ， 而 是 只 考虑 12 个 独立 的 操作 〈 见 表 7.1)〉 ， 每 
种 方法 都 有 重 载 形式 ， 它 们 组 成 了 完整 的 41 个 方法 。 


delete(...) 在 特定 的 URL 上 对 资源 执行 HITP DELETE 操 作 





表 7.1 RestTemplate 中 12 个 独立 的 操作 


ee 在 URL 上 执行 特定 的 HTTP 方 法 ， 返 回 包含 对 象 的 

exchangel... 

ResponseEntity， 这 个 对 象 是 从 啊 应 体 中 映射 得 到 的 
ee 在 URL 上 执行 特定 的 HITP 方 法 ， 返 回 一 个 从 啊 应 体 上 映射 得 到 的 
eXecute(...) 对 象 





发 送 一 个 HTTP GET 请 求 ， 返 回 的 ResponseEntity 包 含 了 啊 应 体 
getForEntity(...) 所 映射 成 的 对 象 


发 送 一 个 HTTP GET 请 求 ， 返 回 的 请 求 体 将 映射 为 一 个 对 象 
发 送 HTTP HEAD 请求， 返回 包含 特定 资源 UREL 的 HITP 头 信息 
发 送 HTTP OPTIONS 请 求 ， 返 回 特定 URL 的 Allow 头 信息 
发 送 HTTP PATCH 请 求 ， 返 回 一 个 从 啊 应 体 映 射 得 到 的 对 和 象 


POST 数据 到 一 个 URL， 返 回 包含 一 个 对 象 的 ResponseEntity， 
这 个 对 象 是 从 啊 应 体 中 映射 得 到 的 








postForEntity(...) 






postForLocation(...) |]POST 数 据 到 一 个 URL， 返 回 新 创建 资源 的 URL 


POST 数据 到 一 个 URL， 返 回 根据 啊 应 体 匹 配 形成 的 对 象 


put(...) PUT 资源 到 特定 的 URL 





除了 TRACE 以 外 ，RestTemplate 对 每 种 标准 的 HITP 方 法 都 提供 了 
至 少 一 个 方法 。 除 此 之 外 ，execute0 和 exchange0O 提 供 了 较 低 层次 的 通用 
方法 ， 以 便于 进行 任意 的 HTTP 操 作 。 


表 7.1 中 的 大 多 数 操作 都 以 3 种 方法 的 形式 进行 了 重 载 。 


。 使 用 String 作 为 URL 格 式 ， 并 使 用 可 变 参 数列 表 指 明 URL 人 参数。 

。 使 用 String 作 为 URL 格 式 ， 并 使 用 Map<String,String> 指 明 URL 参 
数 。 

。 使 用 java.net.URI 作 为 URL 格 式 ， 不 支持 参数 化 URL。 


明确 了 RestTemplate 所 提供 的 12 个 操作 以 及 各 个 变种 如 何 工 作 之 
后 ， 你 了 驶 能 以 目 己 的 方式 编写 消费 REST 资 源 的 客户 病 了 了 。 


要 使 用 RestTemplate， 你 可 以 在 需要 的 地 方 创 建 一 个 实例 : 


也 可 以 将 其 声明 为 一 个 bean 并 注入 到 需要 的 地 方 : 


QBean 
public RestTemplate restTemplate() { 


return new RestTemplate(); 


} 





我 们 通过 对 4 个 主要 HTTP 方 法 (GET、PUT、DELETE 和 POST) 的 
文 持 来 研究 RestTemplate 的 操作 。 下 耐 我 们 从 GET 方 法 的 getForObject() 
和 getForEntityO 开 始 。 


7.1.1 GET 资源 


假设 我 们 现在 想 要 通过 Taco Cloud API 获 取 某 个 配料 ， 并 且 API 没 有 
实现 HATEOAS， 那 么 我 们 可 以 使 用 getForObjectO 获 取 配 料 。 例 如 ， 如 
下 的 代码 将 使 用 RestTemplate 根 据 ID 来 获取 Ingredient 对 象 : 


| public Ingredient getIngredientById(String ingredientId) { 


return rest.getForobject("http://Localhost:8686/ingredients/{id+”， 
Ingredient.class, ingredientId); 





在 这 里 ， 我 们 使 用 了 getForObjectO 的 变种 形式 ， 接 收 一 个 String 类 
型 的 UREL 并 使 用 可 变 列 表 来 指定 UREL 变 量 。 传 递 给 getForObjectO 的 
ingredientId 参 数 会 用 来 填充 给 定 UREL 的 {fid} 占 位 符 。 尽 管 在 本 例 中 只 有 
一 个 URL 变 量 ， 但 是 很 重要 的 一 点 需要 我 们 注意 ， 变 量 参数 会 按照 它们 
出 现 的 顺序 设置 到 占 位 符 中 。getForObject0) 方 法 的 第 二 个 参数 是 啊 应 应 
该 绑 定 的 类 型 。 在 本 例 中 ， 啊 应 数据 《很 可 能 是 JSON 格 了 式 ) 应 该 航 反 
序列 化 为 要 返回 的 mgredient 对 象 。 


万 外 一 种 人 普 代 方案 是 使 用 Map 来 指定 URL 变 量 : 


public Ingredient getIngredientById(String ingredientId) { 
Map<string,string> urlVariables = new HashMap<>() ; 
urlVariables.put("id", ingredientId); 


return rest.getForObject("http://localhost:806086/ingredients/{id}", 
Ingredient.class, urlVariables); 





在 本 例 中 ，ingredientId 的 值 会 被 殴 射 到 名 为 id 的 key 上 。 当 及 起 请 求 
的 时 候 ，{id} 占 位 符 将 会 被 蔡 换 为 key 为 id 的 Map 条 目 上 。 


使 用 URL 参 数 要 稍微 复杂 一 些 ， 这 种 方式 需要 我 们 在 调用 
getForObject0 之 前 构建 一 个 URI 对 象 。 在 其 他 方面 ， 它 与 男 外 两 个 变种 
韭 党 类 似 : 





public Ingredient getIngredientById(String ingredientId) { 
Map<String,String> urlVariables = new HashMap<>() ; 
urlVariables.put("id", ingredientId); 
URI url = UriComponentsBuilder 
.fromHttpUrl("http://localhost:86806/ingredients/{id}") 


.build(urlVariables); 


return rest.getForObject(url, Ingredient.c]lass); 


} 





在 这 里 ，URI 对 象 是 通过 String 规 范 定 义 的 ， 它 的 占 位 人 符 会 被 Map 中 
的 条 目 所 蔡 换 ， 与 之 前 看 到 的 getForObjectO 变 种 非 党 相似 。 
getForObjectO 古 获取 资源 的 有 效 方式 ， 但 是 如 条 澡 己 痪 需要 的 不 仅仅 是 
载 何 体 ， 那 么 可 以 考虑 使 用 getForEntity()。 


getForEntity() 的 工作 方式 和 getForObject() 类 似 ， 但 是 它 所 返回 的 并 
不 是 代表 啊 应 载 何 的 领域 对 象 ， 而 是 一 个 包 于 领 域 对 象 的 
ResponseEntity 对 象 。 借 助 ResponseEntity 对 象 能 够 访问 很 多 的 啊 应 细 
节 ， 比 如 啊 应 头 信息 。 


例如 ， Na 还 想 要 从 啊 应 中 探 和 在 Date 
头 信 息 。 借 助 getForEntity()， 这 个 需求 很 容易 实现 : 


public Ingredient getIngredientById(String ingredientId) { 
ResponseEntity<Ingredient> responseEntity = 
rest.getForEntity("http://localhost:8060806/ingredients/{id}",， 
Ingredient.class, ingredientId); 


log.info("Fetched time: " + 
FesponseEntity .getHeaders() .getDate() ) ; 


return responseEntity .getBody( ) ; 





} 


getForEntity(O 有 与 getForObjectO 方 法 相同 参数 的 重 载 形 式 ， 所 以 我 
们 既 可 以 以 可 变 列 表 参 数 的 形式 提供 URL 杰 量 ， 也 可 以 以 URI 对 象 的 形 
式 调 用 getForEntity()。 


7.1.2 PUT 资源 


为 了 发 送 HTTP PUT 请 求 ，RestTemplate 提 供 了 put0 方 法 。putO 方 法 
的 3 个 变种 形式 都 会 接收 一 个 Object， 它 会 被 序列 化 并 发 送 至 给 定 的 
URL。 就 URL 本 刁 来 讲 ， 它 可 以 以 URI 对 象 或 String 的 形式 来 指定 。 与 
getForObject0 和 getForEntityO 关 似 ，URL 弯 量 能 够 以 可 变 参 数列 表 或 
Map 的 形式 来 提供 。 


假设 我 们 想 要 使 用 一 个 新 Ingredient 对 象 的 数据 来 葵 换 某 个 配料 资 
源 ， 那 么 如 下 的 代码 户 段 融 能 做 到 这 一 所 : 


public void updateIngredient(Ingredient ingredient) { 
Pest .put("http:// Localhost:8686/ingredients/{fid+”， 


ingredient, 
ingredient.getId()); 





在 这 里 ，URL 是 以 String 的 形式 指定 的 。 访 URL 包含 一 个 占 位 从， 
它 会 家 给 定 mgredient 的 id 属性 所 符 换 。 要 友 庆 的 数据 是 Ingredient 对 象 本 
丑 。Pput(0) 方 法 返回 的 是 void， 上 所 以 没有 必要 处 理 返 回 值 。 


7.1.3 ”DELETE 资源 


假说 Taco Cloud 不 再 想 要 提供 条 种 配料 ， 因 此 要 从 可 选 列 表 中 将 其 
完全 删除 。 为 了 实现 这 一 点 ， 我 们 可 以 使 用 RestTemplate 来 调用 delete() 
方法 : 


| public void deleteIngredient(Ingredient ingredient) { 


rest.delete("http://localhost:806806/ingredients/{id}", 
ingredient.getId()); 





在 本 例 中 ， 我 们 只 为 delete0) 提 供 了 URL〈 以 String 的 形式 指定 〉 和 
URL 变 量 值 。 但 是 ， 和 其 他 的 RestTemplate 方 法 类 似 ，URL 能 够 以 URI 
对 象 的 方式 来 指定 ， 并 且 URL 参 数 也 能 够 以 Map 的 方式 来 声明 。 


、 


7.1.4 POST 资源 


现在 ， 假 设 要 添加 新 的 配料 到 Taco Cloud 有 六 单 中 ， 我 们 可 以 
向 “.../ingredients” 端 点 发 送 HTTP POST 请 求 并 将 配料 数据 放 到 请 求 体 
中 。RestTemplate 有 3 种 发 迹 POST 请 求 的 方法 ， 每 种 方法 都 有 相同 的 重 
载 变 种 来 指定 URL。 如 果 你 希望 在 POST 请 求 之 后 得 到 新 创建 的 
Ingredient 资 源 ， 那 么 可 以 按照 如 下 方式 使 用 postForObject(): 


public Ingredient createIngredient(Ingredient ingredient) { 
return rest.postForObject("http://localhost:806806/ingredients",， 


ingredient, 
Ingredient.class); 





postForObjectO 方 法 的 这 个 变种 形式 接收 一 个 String 类 型 的 URL 规 
沁 、 要 提交 给 服务 器 病 的 对 象 以 及 啊 应 体 应 该 绑 定 的 领域 类 型 。 尺 官 我 
们 在 这 里 没有 用 到 ， 但 是 第 4 个 参数 可 以 古 URL 人 变量 值 的 Map 或 者 是 可 
变 参 数 的 列表 ， 它 们 能 够 瞪 换 到 UREL 之 中 。 


如 末 各 户 痛 还 想 要 知道 新 创建 资源 的 地 址 ， 那 么 我 们 可 以 调用 
postForLocation() 方 法 : 


public URI createIngredient(Ingredient ingredient) { 
return rest.postForLocation("http://localhost:8060806/ingredients",， 


ingredient ) ; 





注意 ，postForLocation() 的 工作 方式 与 postForObject() 类 似 ， 只 不 过 
它 所 返回 的 是 新 创建 资源 的 URI， 而 不 是 资源 对 象 本 和 刁 。 这 里 所 返回 的 
URI 是 从 啊 应 的 Location 尖 信息 中 派生 出 来 的 。 如 果 你 同时 需要 地 址 和 
吧 应 载 何 ， 那 么 可 以 使 用 postForEntity0) 方 法 : 
public Ingredient createIngredient(Ingredient ingredient) { 
ResponseEntity<Ingredient> responseEntity = 
rest.postForEntity("http://localhost:8060806/ingredients",， 


ingredient, 
Ingredient.class); 


log.info("New resource created at " + 
responseEntity.getHeaders().getLocation()); 


return responseEntity .getBody( ) ; 





} 


尽管 RestTemplate 的 方法 在 目的 上 有 所 不 同 ， 但 是 它们 的 用 法 非 各 
相似 。 因 此 ， 我 们 很 容易 就 可 以 精通 RestTemplate 并 将 其 用 到 客户 病 代 
伺 中 。 


男 一 方面 ， 如 果 你 所 消费 的 API 在 啊 应 中 包含 了 超 链 接 ， 那 么 
RestTemplate 残 力 所 不 及 了 。 当 然 ， 我 们 可 以 使 用 RestTemplate 获 取 更 评 
细 的 资源 数据 ， 然 后 处 理 里 面 所 包含 的 内 容 和 链接 ， 但 是 这 个 任务 并 不 
简单 。 与 其 使 用 RestTemplate 来 处 理 超 媒 体 API， 还 不 如 选择 一 个 专门 关 
注 该 领域 的 库 ， 那 束 是 Traverson。 


7.2 ”使 用 Traverson 导航 REST API 


Traverson 来 源 于 Spring Data HATEOAS 项 目 ， 是 Spring 应 用 中 开 箱 
即 用 的 消费 超 媒体 API 的 解决 方案 。 这 个 基于 Java 的 库 灵 感 来 源 于 同名 
的 JavaScript 库 。 


你 可 能 已 经 发 现 Traverson 的 名 字 有 点 类 似 于 “traverse on”， 这 种 叫 
法 其 实 可 以 很 好 地 描述 它 的 用 法 。 在 本 市 中 ， 我 们 将 会 以 退 历 API 关 系 
名 的 方式 来 消费 API。 


要 使 用 Traverson， 首 先 我 们 要 用 API 的 基础 URI 来 实例 化 一 个 
Traverson 对 象 : 


Traverson traverson = new TFaverson( 





URI.create("http://localhost:806806/api"), MediaTypes .HAL JSON); 


在 这 里 ， 我 将 Traverson 指 同 了 Taco Cloud 的 基础 URL (本 地 运 
行 ) 。 这 有 是 需要 给 Traverson 指 定 的 唯一 URL。 从 这 里 开始 ， 我 们 残 可 以 
根据 链接 的 关系 名 来 表 历 API。 我 们 同时 还 指定 了 API 将 会 生成 JSON 格 
式 的 啊 应 ， 并 且 具 有 HAL 风 格 的 超 链 接 ， 这 样 Traverson 束 能 知道 怎样 解 
析 传 入 的 资源 数据 了 。 与 RestTemplate 类 似 ， 你 可 以 选择 在 使 用 
Traverson 对 象 之 前 实例 化 它 ， 也 可 以 将 其 声明 为 一 个 bean 并 在 需要 的 地 
方 注 入 进来 。 


有 了 Traverson 对 象 之 后 ， 我 们 就 可 以 退 过 以 下 链接 使 用 API。 例 
如 ， 假 设 我 们 想 检 索 所 有 配料 的 列表 。 从 6.3.1 小 节 可 以 知道 ， 配 料 链 接 


有 一 个 href 属 性 ， 它 会 链接 到 配料 资源 。 我 们 圾 要 跟踪 这 个 链接 : 


ParameterizedTypeReference<Resources<Ingredient>> ingredientType = 
new ParameterizedTypeReference<Resources<Ingredient>>() {}; 


Resources<Ingredient> ingredientRes = 
traverson 
.follow("ingredients") 
.toObject(ingredientType); 


Collection<Ingredient> ingredients = ingredientRes.getContent(); 





通过 调用 Traverson 对 和 象 的 follow0 方 法 ， 我 们 就 可 以 导航 至 链接 天 
系 名 为 ingredients 的 人 资源。 现在， 客户 病 已 经 寻 和 贞 全 ingredients， 我 们 需 
要 通过 调用 toObject0) 来 提取 资源 的 内 容 。 


我 们 需要 告诉 toObject(0) 方 读 要 将 数据 谈 入 到 哪 种 对 象 之 中 。 考 谍 到 
我 们 需要 以 Resources<Ingredient> 对 象 的 形 陈 来 谈 入 ， 而 且 Java 关 型 欣 除 
使 得 为 泛 型 提供 类 型 信息 变 得 非 芝 困难， 所 以 这 可 能 会 有 些 环 手 。 但 
是 ， 创 建 ParameterizedTypeReference 能 够 帮助 我 们 解决 这 个 问题 。 


打 个 比方 ， 假 设 这 不 是 REST API， 而 是 Web 站 点 上 的 主页 ; 这 也 不 
征 REST 各 户 姗 代 权 ， 而 十 我 们 正在 浏 虎 郑 中 否 看 主页 。 在 页 面 中 ， 我 
们 看 到 了 一 个 关于 mgredients 的 链接 ， 点 击 进入 该 链接 。 在 进入 下 一 个 
页 面 的 时 候 ， 我 们 需要 读 取 该 页 面 ， 类 似 于 Traverson 将 内 容 提取 为 


Resources<Ingredient> 对 象 。 
现在 ， 我 们 考虑 一 个 更 有 趣 的 场景 一 一 假设 我 们 想 要 获取 最 新 创 建 


的 taco。 从 主 资源 开始 ， 我 们 可 以 按照 如 下 方式 导航 至 最 近 的 taco 资 
源 : 


ParameterizedTypeReference<Resources<Taco>> tacoType = 
new ParameterizedTypeReference<Resources<Taco>>() {}; 


Resources<Taco> tacoRes = 
traverson 
.follow("tacos") 
.follow("recents") 
.toObject(tacoType); 


Collection<Taco> tacos = tacoRes.getContent(); 





文 里 ， 我 们 跟踪 tacos 链 接 ， 然 后 从 这 里 开始 ， 跟 踩 recents 链 接 。 
这 种 方式 ， 我 们 得 到 了 感 兴趣 的 资源 ， 所 以 基于 对 应 的 
pameeed peteteeneeh 用 toObject0 方 法 ， 我 们 束 得 到 了 想 要 的 内 
。 我 们 可 以 通过 列 出 关系 名 称 列表 的 形式 来 何 化 “.follow0” 方 法 : 


Resources<Taco> tacoRes = 
traverson 


.follow("tacos", "recents") 
.toObject(tacoType); 





正如 我 们 所 看 到 的 ，Traverson 能 够 很 容易 地 导航 HATEOAS 的 API 
并 消费 其 资源 。 但 是 ， 它 并 没有 提供 通过 这 些 API 与 入 或 删除 资源 的 方 
法 。 相 反 ，RestTemplate 能 够 写 入 和 删除 资产， 但 是 在 导航 API 方 面 文 持 
得 并 不 太 好 。 


当 你 既 要 导航 API 又 要 更 新 或 删除 资源 时 ， 你 需要 组 合 使 用 
RestTemplate 和 Traverson。Traverson 仍 然 可 以 导航 至 创建 新 资源 的 链 
接 。 然 后 ， 可 以 将 这 个 链接 传递 给 RestTemplate 来 执行 POST、PUT、 
DELETE 或 任何 其 他 需要 的 HTTP 请 求 。 


例如 ， 我 们 想 要 为 Taco Cloud 深 单 添 加 一 个 新 的 mgredient， 如 下 的 


addIngredient 0 方法 将 Traverson 和 RestTemplate 组 合 起 来 ， 同 API 提 交 了 
一 个 新 的 Ingredient: 


private Ingredient addIngredient(Ingredient ingredient) { 
String ingredientsUrl = traverson 
.follow("ingredients") 
.asLink() 
.getHref() ; 


return rest.postForobJject(ingredientsUr1l， 
ingredient, 
Ingredient.class); 





在 跟踪 完 mngredients 之 后 ， 我 们 通过 调用 asLink0) 方 法 得 到 链接 本 
身 。 基 于 该 链接 ， 我 们 调用 getHrefO 得 到 链接 的 URL。 有 了 URL 之 后 ， 
我 们 就 具备 了 使 用 RestTemplate 调 用 postForObject() 并 创建 新 配料 所 需 的 
一 切 。 


pf 


。 客户 端 可 以 使 用 RestTemplate 针 对 REST API 发 送 HTTP 请 求 。 
。 Traverson 能 够 让 客户 闹 导 航 啊 应 中 内 散 超 链接 的 API。 


本 草 内 容 : 


异步 化 的 请 奶 


使 用 JMS、RabbitMQ 和 Kafka 发 送 消息 


从 代理 拉 取 消 奶 


监听 消息 





在 星期 五 下 午 4 点 55 分 ， 再 有 几 分 钟 你 就 可 以 开始 休假 了 。 现 在 ， 
你 的 时 间 只 够 开车 到 机 场 赶 上 航班 。 但 是 在 你 离开 办 公 室 之 前 ， 你 需要 
确定 老板 和 同事 了 解 你 目前 的 工作 进展 ， 这 样 他 们 就 可 以 在 星期 一 继续 
完成 你 留 下 的 工作 。 不 过 ， 你 的 一 些 同事 已 经 提前 离开 过 周末 去 了 ， 而 
你 的 老板 正在 忙于 开会 。 你 该 怎么 办 呢 ? 

要 想 既 传达 到 你 的 工作 状态 又 能 赶 上 飞机 ， 最 有 效 的 方式 就 是 发 送 


一 封 电子 邮件 给 你 的 老板 和 同事 ， 评 述 工作 进展 并 且 承 访 给 他 们 寄 张 明 
信 厂 。 你 不 知道 他 们 在 哪里 ， 也 不 知 媚 他 们 什么 时 候 才 能 真正 读 到 你 的 


邮件 。 但 是 你 知道 ， 他 们 终 完 会 回 到 他 们 的 苏 公 条 劳 ， 阅 读 你 的 邮件 。 
而 此 时 ， 你 可 能 正在 赶 往 机 场 的 路 上 。 


同步 通信 ， 比 如 我 们 在 前 面 所 看 到 的 REST， 有 它 目 己 的 适用 场 
景 。 不 过 ， 对 于 开 及 者 而 言 ， 这 种 通信 方式 并 不 是 应 用 程序 之 加 进行 区 
互 的 唯一 方式 。 弄 步 消息 是 一 个 应 用 程序 同 万 一 个 应 用 程序 间接 妇 送 消 
恩 的 一 种 方式 ， 这 种 间接 性 能 够 为 进行 通信 的 应 用 市 来 更 松散 的 硒 合 和 
更 大 的 可 伸缩 性 。 


在 本 草 中 ， 我 们 将 会 使 用 异步 消息 从 Taco Cloud Web 站 点 发 大 订单 

言 轧 到 一 个 单独 的 应 用 中 ， 这 个 应 用 是 Taco Cloud 的 厨房 ， 在 这 里 会 页 
天 jtaco。 我 们 将 会 考虑 Spring 提 供 的 3 种 异步 消 恩 方 采 : Java 消 息 服 务 

(Java Message Service，JMS) 、RabbitMQ 和 融 级 消 居 队列 协议 

(Advanced Message Queueing Protocol) 、Apache Kafka。 除 了 基础 的 
及 达 和 接收 消 县 之 外 ， 我 们 还 会 看 一 下 Spring 对 消息 驱动 POJO 的 文 持 ， 
它 是 一 种 与 EJB 的 消 晨 驱动 Bean (Message-Driven Bean，MDB) 类 似 的 
消 妃 接收 方式 。 


8.1 使 用 JMS 发 送 消息 


JMS 是 一 个 Java 标 准 ， 定 义 了 使 用 消息 代理 《message broker) 的 通 
用 API， 最 早 于 2001 年 提出 。 长 期 以 来 ，JMS 一 直 是 实现 异步 消 因 的 站 
选 方案 。 在 JMS 出 现 之 前 ， 每 个 消息 代理 都 有 私有 的 API， 这 残 使 得 不 
辣 代理 之 间 的 消息 代码 很 难 通用 。 但 是 信 助 JMS， 上 所 有 章 从 规范 的 实现 
都 使 用 通用 的 接口 ， 这 就 好 像 ]JDBC 为 数据 库 操 作 提 供 了 通用 的 接口 一 


样 。 


Spring 通过 基于 模板 的 抽象 为 JMS 功 能 提供 了 支持 ， 这 个 模板 就 是 
JmsTemplate。 借 助 JmsTemplate， 我 们 能 够 非常 容易 地 在 消 明 生产 方 发 
送 队 列 和 主题 消 奶 ， 在 消费 消 姑 的 那 一 方 ， 也 能 够 非 第 容易 地 接收 这 些 
消息 。Spring 还 提供 了 消息 驱动 POJO 的 理念 : 这 是 一 个 简单 的 Java 对 
象 ， 它 能 够 以 异步 的 方式 啊 应 队列 或 主题 上 到 达 的 消 居 。 


我 们 将 会 讨论 Spring 对 JMS 的 文 持 ， 包 括 JmsTemplate 和 消 因 驱动 
POJO。 但 是 在 及 送 和 接收 消 恩 之 前 ， 我 们 首先 需要 一 个 消息 代理 
(broker) ， 它 能 够 在 消 居 的 生产 者 和 消费 者 之 间 传 递 消 居 。 对 Spring 
JMS 的 探索 吏 从 在 Spring 中 挫 建 消息 代理 开始 吧 。 


8.1.1 搭建 JMS 环 境 


在 使 用 JMS 之 前 ， 我 们 必须 要 将 JMS 客 户 端 添 加 到 项 目的 构建 文件 
中 。 借 助 Spring Boot， 这 再 人 简单 不 过 了 了。 我们 所 需要 做 的 束 古 瀛 加 一 个 
starter 依 赖 到 构建 文件 中 。 但 是 ， 首 先 ， 我 们 需要 决定 该 使 用 Apache 
ActiveMQ 还 是 更 新 的 Apache ActiveMQ Artemis 代 理 。 


如 果 选 择 使 用 Apache ActiveMQ， 那 么 我 们 需要 添加 如 下 的 依赖 到 
项 目的 pom.xml 文 件 中 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-activemq</artifactId> 
</dependency> 





如 果 选 择 使 用 ActiveMQ Artemis， 那 么 starter 依 赖 将 会 如 下 所 示 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-artemis</artifactId> 
</dependency> 





Artemis 是 重 儿 实现 的 下 一 代 ActiveMQ， 使 ActiveMQ 变 成 了 遗留 方 
案 。 因 此 ，Taco Cloud 会 选择 使 用 Artemis。 但 是 在 编写 发 送 和 接收 消 忌 
的 代码 方面 ， 选 择 哪 种 方案 几乎 没有 什么 影响 。 唯 一 南 要 广 意 的 重要 产 
异 束 是 如 何 配 置 Spring 创 建 到 代理 的 连接 。 


默认 情况 下 ，Spring 会 假定 Artemis 代 理 在 localhost 的 61616 尊 口 运 
行 。 对 于 开发 来 说 ， 这 样 是 没有 问题 的 ， 但 是 一 旦 要 将 应 用 部 著 到 生产 
环境 ， 我 们 就 需要 设置 一 些 属 性 来 告诉 Spring 访 如 何 访 问 代 理 。 最 有 用 
的 属性 如 胡 8.1 所 示 。 


表 8.1 ”配置 Artemis 代 理 的 位 置 和 和 凭证 信息 的 属性 





例如 ， 我 们 看 看 如 下 的 application.yml 文 件 条 目 ， 它 可 能 会 用 于 一 
个 韭 开 发 的 环境 : 


spring: 
artemis: 
host: artemis.tacocloud.com 


port: 61617 
user: tacoweb 
password: 13tm31n 





这 会 让 Spring 创建 到 Artemis 代 理 的 连接 ， 访 Artemis 代 理 监 听 
artemis.tacocloud.com 的 61617 端 口 。 它 还 为 应 用 设置 了 与 代理 交互 的 凭 
证 信息 。 和 凭证 信息 是 可 选 鸭 ， 但 是 对 于 生产 环境 来 说 ， 我 们 推荐 使 用 它 
们 。 


如 果 你 选择 使 用 ActiveMQ 而 不 是 Artemis， 那 么 需要 使 用 ActiveMQ 
特定 的 属性 ， 如 表 8.2 所 示 。 


表 8.2 ”配置 ActiveMQ 代 理 的 位 置 和 和 凭证 信息 的 属性 


spring.activemdq.broker-url 代理 的 URL 


Ee aa i 
EE | aaaenwnaaama i 





需要 注意 ，ActiveMQ 代 理 不 是 分 别 设 置 代 理 的 主机 和 端口 ， 而 是 
使 用 了 一 个 名 为 Spring.activemdq.broker-url 的 属性 来 指定 代理 的 地 址 。 
UREL 应 该 是 "tcp://” 协 议 的 地 址 ， 如 下 面 的 YMAE 片段 所 示 : 


Spring : 
activemq: 


broker-url: tcp://activemq.tacocloud.conm 
user: tacoweb 
password: 13tm31n 





不 管 你 是 选择 Artemis 还 是 ActiveMQ， 如 果 是 在 本 地 开发 运行 ， 那 
么 你 都 不 需要 配置 这 些 必 性。 


但 是 ， 如 果 你 选择 使 用 ActiveMQ， 需 要 将 spring.activemq.in- 
memory 属 性 设置 为 false， 防 止 Spring 启 动 内 存 中 运行 的 代理 。 内 存 中 运 
行 的 代理 看 起 来 很 有 用 ， 但 十 只 有 同一 个 应 用 友 布 和 消费 消 晨 时 才能 使 
用 它 〈 这 限制 了 它 的 用 途 〉。 


在 继续 下 面 的 内 容 之 有 前， 我 们 要 安装 并 局 动 一 个 Artemis (或 
ActiveMQ) 代理 ， 而 不 是 选择 使 用 磐 入 陈 的 代理 。 我 在 这 里 不 再 重复 
讲述 安装 过 程 ， 推 大 你 参考 Artemis 和 ActiveMQ 的 文档 来 了 解 详细 内 


AAAN 


合 。 


现在 ， 我 们 已 经 在 构建 文件 中 添加 了 对 JMS starter 的 依 顿 ， 代 理 也 
己 经 准备 好 将 消 因 从 一 个 应 用 传递 到 男 一 个 应 用 。 接 下 来 ， 我 们 就 可 以 
开始 发 送 消 息 了 。 


8.1.2 ”使 用 JmsTemplate 发 送 消 县 


将 JMS starter 依 赖 〈 不 管 是 Artemis 还 是 ActiveMQ ) 添加 到 构建 文件 
之 后 ，Spring Boot 会 目 动 配置 一 个 JmsTemplate〈 以 及 其 他 内 容 ) ， 我 们 
可 以 将 它 注 入 到 其 他 bean 中 ， 并 使 用 它 来 发 送 和 接收 消 轧 。 


JmsTemplate 是 Spring 对 JMS 集 成 文 持 功能 的 核心 。 与 Spring 其 他 面 
器 模板 的 组 件 类 似 ，JmsTemplate 消 除了 大 量 传 统 使 用 JMS 时 所 需 的 样板 
(Cs op 那么 我 们 需要 编写 代码 来 创建 到 消 
恩 代 理 的 连接 和 和 会话 ， 还 要 编写 更 多 的 代码 来 处 理发 这 消 恩 过 程 中 可 能 
出 现 的 异常 。JmsTemplate 能 够 让 我 们 关注 真正 要 做 的 事情 发 送 消 


J 已 vo 


JmsTemplate 有 多 个 用 来 发 送 消 居 的 方法 ， 包 括 : 


// 发 大 原始 的 消 妃 

void send(MessageCreator messageCreator) throws JmsException,; 

void send(Destination destination, MessageCreator messageCreator) 
throws JmsException; 

void send(String destinationName, MessageCreator messageCreator) 
throws JmsException; 

// 友 壕 根据 对 象 转换 而 成 的 消 忆 

void convertAndSend(Object message) throws JmsException; 

void convertAndSend(Destination destination, Object message) 
throws JmsException; 


void convertAndSend(String destinationName, Object message) 
throws JmsException; 


// 及 送 根据 对 象 转换 而 成 的 消 四 并 且 珊 有 后 期 处 理 的 功能 
void convertAndSend(Object message, 
MessagePostProcessor postProcessor) throws JmsException; 
void convertAndSend(Destination destination, Object message, 
MessagePostProcessor postProcessor) throws JmsException; 
void convertAndSend(String destinationName, Object message, 
MessagePostProcessor postProcessor) throws JmsException; 





我 们 可 以 看 到 ， 实 际 上 只 有 两 个 方法 ， 也 束 是 sendO 和 和 


coOnvertAndSend0， 每 个 方法 都 有 重 载 形 却 以 文 持 不 同 的 参数 。 如 果 我 
们 仔细 观察 一 下 ， 就 会 发 现 convertAndSend0 的 各 种 形式 又 可 以 分 成 两 
个 子 类 型 。 在 考虑 这 些 方法 作用 的 时 候 ， 我 们 对 它们 进行 以 下 细 分 。 


。 3 个 send() 方 法 都 需要 MessageCreator 来 生成 Message 对 象 。 

。 3 个 convertAndSend() 方 法 会 接受 Object 对 象 ， 并 且 会 在 秦 后 目 动 将 
Object 转换 为 Message。 

。 3 个 convertAndSend0 会 目 动 将 Object 转换 为 Message， 但 同时 还 能 接 
受 一 个 MessagePostProcessor 对 象 ， 用 来 在 发 送 之 前 对 Message 进 行 
目 定 义 。 


这 3 种 方法 分 类 部 分 列 包含 3 个 童 载 方法 ， 它 们 的 区 别 在 于 如 何 指 


定 JMS 的 目的 地 《队列 或 主题 ) 。 


e。 有 1 个 方法 不 接受 目的 地 参数 ， 它 会 将 消息 发 送 至 默认 的 目的 地 。 
。 有 1 个 方法 接受 Destination 对 象 ， 访 对 象 指定 了 消息 的 目的 地 。 
。 有 1 个 方法 接受 String， 它 通过 名 字 的 形式 指定 了 消息 的 目的 地 。 


要 让 这 些 方法 真正 肥 挥 作用 ， 我 们 看 一 下 程序 清单 8.1 中 的 
JmsOrderMessaging Service， 它 使 用 了 形 却 最 答 单 的 send0) 方 法 。 


程序 清单 8.1 使 用 .send() 方 法 将 订单 用 送 至 默认 的 目的 地 





package tacos.messaging,; 


import 
import 
import 


import 
import 
import 
import 


JavaxX.Jms.JMSException; 
]avax.jms.Message ; 
]avax.jms.Sesslion; 


org.springframework.beans .factory .annotation.Autowlred ; 
org.springframework.Jjms.core.JmsTemp]ate ; 
org.springframework.Jjms.core.MessageCreator ; 
org.springframework.stereotype.Service; 


QService 
public class JmsOrderMessagingService implements OrderMessagingService { 
private JmsTemplate jms; 


QAutowired 
public JmsOrderMessagingService(JmsTemplate jms) { 
this.jms = jms; 


} 


QOverride 
public void sendOorder(Order order) { 
jms.send(new MessageCreator() { 
QOverride 
public Message createMessage(Session session) 
throws JMSException { 
return session.createObjectMessage(order); 


} 
} 
» 


sendOrder() 方 法 调用 了 jms.send()， 并 传递 了 MessageCreator 接 口 的 
一 个 匿名 内 部 实现 。 这 个 实现 类 重 写 了 createMessage() 方 法 ， 从 而 能 够 
通过 给 定 的 Order 对 象 创 建新 的 对 象 消 息 。 


我 不 知道 你 的 感 沉 如何， 但 是 我 认为 程序 清单 8.1 虽 然 比较 直接 ， 
但 还 是 有 点 吵 唆 。 声 明 匿 名 内 部 类 的 过 程 使 得 原本 很 向 单 的 方法 调用 变 
得 很 复杂 。 我 们 发 现 MessageCreator 是 一 个 函数 式 接口 ， 所 以 我 们 可 以 
通过 lambda 表 达 式 简化 一 下 sendOrder() 方 法 : 


QOverride 
public void sendorder(Oorder order) { 


jms.send(session -> session.createObjectMessage(order)); 





但 是 ， 需 要 注意 对 jms.send0 的 调用 并 没有 指定 目的 地 。 为 了 让 它 能 


够 运行 ， 我 们 需要 退 过 名 为 spring.jms.template.default-destination 罗 属性 
声明 一 个 默认 的 目的 地 名 称 。 例 如 ， 我 们 可 以 在 application.yml 文 件 中 
这 样 设置 该 属性 : 


Spring : 
]Jms : 


template: 
default-destination: tacocloud.order .queue 





在 很 多 场景 下 ， 使 用 默认 的 目的 地 是 最 简单 的 可 选 方案 。 倍 助 它 ， 
我 们 只 声明 一 次 目的 地 和 名称 残 可 以 了 ， 人 代码 只 关心 发 送 消息 ， 而 无 顷 天 
心 消 妃 会 及 到 哪里 。 但 是 ， 如 采 我 们 要 将 消息 发送 至 默认 目的 地 之 外 的 
其 他 地 方 ， 那 么 我 们 需要 通过 为 snd0O 议 置 参数 来 进行 指定 。 

其 中 一 种 方式 就 是 传递 Destination 对 象 作 为 send() 方 法 的 第 一 个 参 
数 。 最 简单 的 方式 就 是 声明 一 个 Destination bean 并 将 其 注入 处 理 消 息 的 
bean 中 。 例 如 ， 如 下 的 bean 声 明 Taco Cloud 订 单 队列 的 Destination: 


QBean 
public Destination orderQueue() { 


return new ActiveMQQUeue("tacocloud.order.queue"); 


} 





很 重要 的 一 点 需要 注意 ， 这 里 的 ActiveMQQueue 来 源 于 Artemis (来 
自 org.apache. activemq.artemis.jms.client 包 ) 。 如 果 选 择 使 用 
ActiveMQ 而 不 是 Artemis) ， 那 么 同样 有 一 个 名 为 ActiveMQQueue 的 


类 〈 来 目 org.apache.activemq.command 包 ) 。 


在 Destination bean 注 入 到 JmsOrderMessagingService 之 后 ， 调 用 
send() 的 时 候 ， 我 们 就 可 以 使 用 它 来 指定 目的 地 了 : 


private Destination orderQueue ; 


QAutowired 
public JmsOrderMessagingService(JmsTemplate jms, 
Destination orderQueue) { 
this.jms = jms; 
this.orderQueue = orderQueue ; 


} 


QOverride 
public void sendOrder(Order order) { 
jms.send ( 
orderQueue, 
session -> session.createObjectMessage(order)); 





通过 Destination 指 定 目 的 地 的 时 候 ， 我 们 其 实 可 以 设置 Destination 
的 更 多 属性 ， 而 不 仅仅 是 目的 地 的 名 称 。 但 是 ， 在 实践 中 ， 除 了 目的 地 
名 称 我 们 几乎 不 会 设置 其 他 的 属性 。 因 此 ， 使 用 名 称 作 为 send0 的 第 一 
个 参数 会 更 加 简单: 
QOverride 


public void sendOrder(Order order) { 
jms.send( 


"tacocloud.order.queue", 
session -> session.createObjectMessage(order)); 





尽管 send(0) 方 法 使 用 起 来 并 不 是 特别 困难 〈 尤 其 是 通过 lambda 表 达 
式 来 实现 MessageCreator 的 时 候 更 是 如 此 ) ， 但 是 它 要 求 我 们 提供 
MessageCreator 还 是 增加 了 一 点 复 尖 性 。 如 来 我 们 能 够 只 指定 要 友和 还 的 
对 象 〈 以 及 可 能 要 用 到 的 目的 地 ) ， 那 己 不 是 更 简单 ? 这 其 实 融 是 
convertAndSend0O 的 工作 原理 。 接 下 来 ， 我 们 看 一 下 这 种 方式 。 


诊 奶 肥 壕 之 前 进行 转换 


JmsTemplates 的 convertAndSend0) 方 法 简化 了 消息 的 及 布 ， 因 为 它 不 
再 需要 MessageCreator。 我 们 将 要 及 送 的 对 象 下 接 传递 给 
convertAndSend()， 这 个 对 象 在 发 这 之 前 会 饭 转 换 成 Message。 


例如 ， 在 如 下 重新 实现 的 sendOrder0O) 方 法 中 ， 使 用 
convertAndSend() 将 Order 对 象 友 送 到 给 定名 称 的 目的 地 : 


QOverride 
public void sendorder(Oorder order) { 


jms.convertAndSend( "tacocloud.order.queue", order); 


} 





与 send0 方 法 类 似 ，convertAndSend() 将 会 接受 一 个 Destination 对 象 
或 String 仁 来 确定 目的 地 ， 我 们 也 可 以 完全 忽略 目的 地 ， 将 消息 用 达到 
默认 目的 地 上 。 


不 官 使 用 哪 种 形式 的 convertAndSend()， 传 递 给 convertAndSend() 的 
Order 孝 会 在 用 大 之 前 转换 成 Message。 在 撒 层 ， 这 是 通过 
MessageConverter 的 实现 关 来 完成 的 ， 它 蕉 我 们 做 了 将 对 象 转换 成 
Message 有 的 脏 活 索 活 。 


配置 消 妃 转换 货 


MessageConverter 是 Spring 定义 的 接口 ， 只 有 两 个 需要 实现 的 方法 : 


public Interface MessageConverter { 
Message toMessage(Object object, Session session) 
throws JMSException, MessageConversionException; 


Object fromMessage(Message message ) 
} 


尽管 这 个 接口 实现 起 来 很 答 单 ， 但 我 们 通 间 并 没有 必要 创建 目 定义 
的 实现 。Spring 已 经 提供 了 多 个 实现 ， 如 表 8.3 所 示 。 


表 8.3 ”Spring 为 通用 的 转换 任务 提供 了 多 个 消息 转换 器 〈 所 有 的 消息 转换 器 都 位 于 


org.Springframework.jms.support.converter 包 中 ) 


消 轧 转换 卉 


MappingJackson2MessageConverter 


MarshallingMessageConverter 


MessagingMessageConverter 


SimpleMessageConverter 





使 用 Jackson 2 JSON 库 实现 消息 与 JSON 格 式 之 间 
的 相互 转换 


使 用 JAXB 库 实现 消息 与 XML 格式 之 间 的 相互 转 
换 


使 用 底层 的 MessageConverter 实 现 消息 抽象 的 
Message 载 集 与 javax.jms.Message 之 间 的 转换 ， 同 
时 会 使 用 JmsHeaderMapper 实 现 JMS 头 信息 与 标 
准 消息 头 信 息 之 间 的 转换 


实现 String 与 TextMessage 之 则 的 相互 转换 、 字 市 
数组 与 BytesMessage 之 间 的 相互 转换 、Map 与 
MapMessage 之 间 的 相互 转换 以 及 Serializable 对 象 
与 ObjectMessage 之 间 的 相互 转换 


黑 认 情况 下 ， 将 会 使 用 SimpleMessageConverter， 但 是 它 需 要 被 发 


送 的 对 象 实 现 Serializable。 这 种 办 法 可 能 也 不 错 ， 但 有 时 候 我 们 可 能 想 
要 使 用 其 他 的 消 奶 转换 妖 来 消除 这 种 限制 ， 比 如 


MappingJackson2MessageConverter。 


为 了 使 用 不 同 的 消 明 转 换 右 ， 我 们 必须 要 做 的 事情 束 是 将 选中 的 背 
轧 转 换 器 实例 声明 为 一 个 bean。 例 如 ， 如 下 的 bean 声 明 将 会 使 用 
MappingJackson2MessageConverter 符 代 SimpleMessageConverter: 
QBean 
public MappingJackson2MessageConverter messageConverter() { 


MappingJackson2MessageConverter messageConverter = 
new Mapping]Jackson2MessageConverter( ) ; 


messageConverter .setTypeIdPropertyName(”typeId ”) ; 
return messageConverter ; 


} 





裔 要 注意 ， 在 返回 之 前 ， 我 们 调用 了 
MappingJackson2MessageConverter 的 SetTypeId PropertyName() 方 法 。 这 
非 各 重要， 因为 这 样 能 够 让 接收 者 知道 传 入 的 请 息 要 转换 成 什么 类 型 。 
堆 认 情况 下 ， 它 将 会 包含 要 转换 的 类 型 的 全 限定 闫 名。 但是， 这 样 的 话 
会 不 太 灵 活 ， 要 求 接收 站 也 包 售 相同 的 突 型 ， 并 且 具 有 相同 的 全 限定 关 
名 。 

为 了 实现 更 大 的 灵活 性 ， 我 们 可 以 通过 调用 消 明 转换 融 有 的 
setTypeldMappings() 方 法 将 一 个 合成 类 型 名 映 冉 到 实际 类 型 上 。 淮 例 来 
襄 ， 消 恩 转 换 颖 bean 方 法 的 如 下 代码 变更 会 将 一 个 合成 的 order 类 型 ID 映 
抽 为 Order 类 : 


Fr 
public MappingJackson2MessageConverter messageConverter() { 


MappingJackson2MessageConverter messageConverter = 
new MappingJackson2MessageConverter(); 
messageConverter.setTypeldPropertyName(" typelId"); 


Map<String, Class<?>> typeIdMappings = new HashMap<String, Class<?>>(); 
typeIdMappings.put("order", Order.class); 
messageConverter .setTypeIdMappings(typeIdMappings ) ; 


return messageConverter ; 





这 样 的 话 ， 消 妃 的 _typeId 属 性 中 残 不 用 及 送 全 限定 类型 了 ， 而 是 会 
发 这 order 价 。 在 接收 闹 的 应 用 中 ， 将 会 配置 类 似 的 消 居 转 换 帮 ， 将 
order 映 喘 为 它 目 己 能 够 理解 的 订单 类 型 。 在 接收 闹 的 订单 可 能 位 于 不 同 
的 包 中 、 有 不 同 的 类 名 ， 甚 至 可 以 只 包含 发 运 者 Order 属 性 的 一 个 子 
售 


0o 


对 消 妃 进行 后 期 处 理 


假设 除了 利润 丰厚 的 Web 业 务 之 外 ，Taco Cloud 还 决定 开 几 家 实体 
的 连锁 taco 店 ， 鉴 于 任何 一 家 餐馆 都 可 能 成 为 Web 业 务 的 运行 中 心 ， 在 
餐馆 中 他 们 需要 有 一 种 方式 告诉 厨房 订单 的 来 源 ， 这 样 厨 房 的 工作 人 员 
就 能 为 店面 里 的 订单 和 Web 上 的 订单 执行 不 同 的 流程 。 


我 们 尽 可 以 在 Order 对 象 上 添加 一 个 新 的 source 属 性 ， 让 它 携 市 该 信 
忌 : 如 末 是 在 线 订 单 ， 束 将 其 设置 为 WEB; 如 采 是 店面 里 的 订单 ， 吏 
将 其 设置 为 STORE。 人 但是， 这样 我 们 残 需要 同时 修改 Web 站 点 的 Order 
美和 厨房 应 用 的 Order 茯 ， 但 实际 上 只 有 taco 的 准备 人 员 需 要 该 信息 。 


有 一 种 更 简单 的 方案 ， 融 是 为 消 上 深 加 一 个 目 定 义 的 头 部 ， 让 和 它 斤 


市 订单 的 来 源 。 如 有 果 我 们 使 用 send0) 方 法 来 肥 送 taco 订 单 ， 那 么 通过 调用 
Message 对 象 的 setStringProperty() 方 法 非常 容易 实现 : 


jms.send("tacocloud.order.queue", 
session -> { 


Message message = session.createObjectMessage(order); 
message.setStringProperty("X ORDER SOURCE", "WEB"); 


}); 





但 是 ， 这 里 的 问题 在 于 我 们 并 没有 使 用 send()。 在 使 用 
convertAndSend() 方 法 的 时 候 ，Message 是 在 确 层 创建 的 ， 我 们 无 法 访问 
到 它 。 


对 好 ， 还 有 一 种 方式 能 够 在 发 送 之 六 修改 展 层 创建 的 Message 对 
象 。 我 们 可 以 传递 一 个 MessagePostProcessor 作 为 convertAndSend() 的 最 
后 一 个 参数 ， 借 助 它 我 们 可 以 在 Message 创 建 之 后 做 任何 想 做 的 事情 。 
如 下 的 代码 依然 使 用 了 convertAndSend()， 但 是 它 能 够 在 消息 发 送 之 前 
使 用 MessagePostProcessor 深 加 X_ORDER_SOURCE 汰 信息 : 


jms.convertAndSend("tacocloud.order.queue", order, new MessagePostProcesso 


r() { 
QOverride 
public Message postProcessMessage(Message message) throws JMSException { 
message.setStringProperty("X ORDER SOURCE", "WEB"); 
return message 





} 
}); 


你 可 能 已 经 及 现 MessagePostProcessor 是 一 个 图 数 式 接口 。 这 和 意味 着 
我 们 可 以 将 匿名 内 部 类 将 换 为 ljambda， 进 一 步 窗 化 它 : 


jms.convertAndSend("tacocloud.order.queue", order., 
message -> { 


message.setStringProperty("X ORDER SOURCE", "WEB"); 
return message,; 


}); 





尽管 在 这 里 我 们 只 是 将 这 个 特殊 的 MessagePostProcessor 用 到 了 本 次 
convertAndSend0) 方 法 调用 中 ， 但 是 你 可 能 会 友 现 在 你 的 代码 中 会 在 不 
同 的 地 方 多 次 调用 convertAndSend()， 它 们 均 会 用 到 相同 的 
MessagePostProcessor。 在 这 种 情况 下 ， 方 法 引用 是 比 lambda 更 好 的 方 
和 荣 ， 筷 能 避免 不 必要 的 代码 重复 : 


@QGetMapping("/convertAndSend/order") 
public String convertAndsendorder() { 
Order order = buildOrder(); 
jms.convertAndSend("tacocloud.order.queue", order., 
this::addorderSource ) ; 
return “ Convert and sent order 


} 


private Message addOrderSource(Message message) throws JMSException { 
message.setStringProperty("X ORDER SOURCE", "WEB"); 
return message ; 


} 





我 们 已 经 看 到 了 多 种 友 送 消息 的 方式 ， 但 是 如 末 消 四 无 人 接收 ， 那 
么 只 及 送 消息 也 没什么 价值 。 搂 下 来 ， 我 们 看 一 下 如 何 使 用 Spring 和 
JMS 接 收 消 电 。 


8.1.3 ”接收 JMS 背 忌 
在 消费 消息 的 时 候 ， 我 们 可 以 选择 拉 取 模式 (pull model) 和 推送 


模式 〈push model〉， 前 者 会 在 我 们 的 代码 中 请 求 消 恩 并 一 直 等 待 且 到 
消息 到 达 为 止 ， 而 后 者 则 会 在 消息 可 用 的 时 候 目 动 在 你 的 代码 中 执行 。 


JmsTemplate 提 供 了 多 种 方式 来 接收 消 晨 ， 但 它们 使 用 的 都 是 拉 取 
模式 \。 io eda annin 而 线程 会 一 直 阻 竖 到 
一 个 消息 抵达 为 止 〈《 这 可 能 马上 友 生 ， 也 可 能 需要 等 竺 一会儿 ) 。 


男 外 ， 我 们 也 可 以 使 用 推送 模式 ， 在 这 种 情况 下 ， 我 们 会 定义 一 个 
消息 监听 器 ， 每 当 有 消息 可 用 时 ， 它 就 会 被 调用 。 

这 两 种 方案 能 够 适用 于 各 种 用 户 场景 。 人 们 普 过 党 得 推送 模式 是 更 
好 的 方案 ， 因 为 它 不 会 阻 窜 线程 ， 但 是 ， 在 某 些 场景 下 ， 如 果 消 居 抵 达 
的 速度 太 快 ， 那 么 监听 需 可 能 会 过 载 。 而 拉 取 模式 允许 消费 者 声明 它们 
何 时 才 为 接收 新 消息 做 好 准备 。 


我 们 将 会 看 一 下 这 两 种 方案 ， 首 先 从 JmsTemplate 提 供 的 拉 取 模式 
开始 。 


使 用 JmsTemplate 来 接收 消息 


JmsTemplate 提 供 了 多 个 对 代理 的 拉 取 方法 ， 其 中 包括 : 


Message receive() throws JmsException; 
Message receive(Destination destination) throws JmsException; 
Message receive(String destinationName) throws JmsException; 


Object receiveAndConvert() throws JmsException; 
Object receiveAndConvert(Destination destination) throws JmsException; 
Object receiveAndConvert(String destinationName) throws JmsException; 





我 们 可 以 看 到 ， 这 6 个 方法 简直 就 是 JmsTemplate 中 send() 和 和 
convertAndSend0) 方 法 的 镜像 。receive(0) 方 法 接收 原始 的 Message， 而 
receiveAndConvertO 则 会 使 用 一 个 配置 好 的 消息 转换 堪 将 消息 转换 成 领 


域 对 象 。 对 于 其 中 的 每 种 方法 ， 我 们 都 可 以 指定 Destination 或 者 包 合 目 
的 地 名 称 的 String 值 ， 人 否则 ， 我 们 将 会 从 寺 认 目的 地 拉 取 消息 。 


为 了 实际 看 一 下 它 是 如 何 运 行 的 ， 我 们 编写 代码 从 
tacocloud.order.queue 目 的 地 拉 取 一 个 Order。 程 序 清单 8.2 展 现 了 
OrderReceiver， 这 个 服务 组 件 会 使 用 JmsTemplate.receive() 来 接收 订单 数 
据 。 


程序 清单 8.2 ”从 队列 拉 取 订单 


package tacos.Kkitchen.messagling.]jms; 

import Javax.Jms.Message; 

import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.jJms.core.JmsTemplate; 

import org.sprIngframework.Jjms.support.converter .MessageConverter ; 
Import org.springframework.stereotype.Component,; 


QComponent 

public class JmsOrderReceiver implements OrderReceiver { 
private JmsTemplate jms; 
private MessageConverter converter ; 


QAutowired 

public JmsOrderReceiver(JmsTemplate jms, MessageConverter converter) { 
this.jms = jms; 
this.converter = Converter ; 


public Order receiveOrder() { 
Message message = jms.receive("tacocloud.order.queue"); 
return (Order) converter.fromMessage(message); 


} 


} 





这 里 我 们 使 用 String 值 来 指定 从 哪个 目的 地 拉 取 订单 。receiveO 返 回 
的 是 没有 经 过 转换 的 Message， 但 是 ， 我 们 真正 需要 的 是 Message 中 的 
Order， 所 以 接 下 来 我 们 要 做 的 事情 束 是 使 用 被 注入 的 消 恩 转换 器 对 消 


恩 进 行 转换 。 消 居中 的 type ID 属性 将 会 
最 


指导 转换 问 将 消 因 转换 成 
Order， 但 它 返 回 的 是 Object， 所 以 在 了 最终 


已, 
-证 
终 返 回 之 前 要 进行 类 型 转换 ，。 


如 果 我 们 要 探查 消息 的 属性 和 消息 头 信息 ， 那 么 接收 诛 始 的 
Message 对 象 可 能 会 非常 有 用 。 但 是 ， 通 第 来 讲 ， 我 们 只 需要 消 县 的 载 
何 。 将 载 何 转换 成 岛 域 对 象 是 一 个 需要 两 步 操 作 的 过 程 ， 而 且 它 需要 将 
消 恩 转换 右 注 入 组 件 中 。 如 果 你 只 天 心 载 何 ， 那 么 使 用 
receiveAndConvertO 会 更 和 价 单一 些 。 程 序 清 单 8.3 展现 了 如 何 使 用 
receiveAndConvertO) 和 丛 换 receive0) 来 重新 实现 JmsOrderReceiver。 


程序 清单 8.3 ”接收 已 经 转换 好 的 Order 对 象 


package tacos.kitchen.messaging.Jjms; 

import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.jJjms.core.JmsTemplate; 

Import org.springframework.stereotype.Component,; 


QComponent 
public class JmsOrderReceiver implements OrderReceiver { 
private JmsTemplate jms; 


Q@Autowired 
public JmsOrderReceiver(JmsTemplate jms) { 
this.jms = jms; 


} 


public Order receiveOrder() { 
return (Order) jms.receiveAndConvert("tacocloud.order.queue"); 


} 





} 


这 个 新 版 本 的 JmsOrderReceiver 的 receieveOrder() 被 简化 到 了 只 有 一 
行 代 码 。 同 时 ， 我 们 不 再 需要 将 MessageConverter 注 入 进来 了 了， 因为 所 
有 的 操作 都 会 在 receiveAndConvert() 方 法 的 从 后 完成 。 


在 继续 学 习 下 面 的 内 容 之 前 ， 我 们 考虑 一 下 如 何在 Taco Cloud 厨 房 
应 用 中 使 用 receiveOrder()。Taco Cloud 厨 房 中 的 厨师 可 能 会 按 下 一 个 按 
钮 或 者 采取 其 他 操作 ， 表 明 他 已 经 准备 好 开始 做 taco 了 。 此 时 ， 
receiveOrder() 会 被 调用 ， 然 后 对 receive() 或 receiveAndConvert() 的 调用 将 
会 阻 旦 。 在 订单 消 居 抵达 之 前 ， 这 里 不 会 友 生 任何 事情 。 一旦 订单 抵 
达 ， 对 receiveOrder() 的 调用 将 会 把 该 订 早 信息 返回 ， 订 单 的 详细 信息 会 
展现 给 厨师 ， 这 样 他 残 可 以 开始 工作 了 。 对 于 拉 取 和 模 陈 来 说 ， 这 似乎 是 
一 种 很 卓然 的 选择 。 


接 下 来 ， 我 们 看 一 下 如 何 通 过 声明 JMS 监 听 霹 来 实现 推送 模式 。 
声明 消息 监听 需 


拉 取 模式 需要 显 式 调用 receive() 或 receiveAndConvert() 才 能 接收 消 
尽 ， 与 之 不 同 ， 消 居 监 昕 旨 是 一 个 密 动 的 组 件 ， 在 消 因 抵达 之 前 ， 它 会 
一 直 处 于 空 用 状态 。 


要 创建 能 够 对 JMS 消 息 做 出 反应 的 消息 监听 左 ， 我 们 需要 为 组 件 中 
的 某 个 方法 添加 @JmsListener 注 解 。 程 序 清单 8.4 展 示 了 一 个 新 的 
OrderListener 组 件 ， 它 会 被 动 地 监听 消息 ， 而 不 是 主动 请 求 消 息 。 


程序 清单 8.4 监听 订单 消息 的 OrderListener 组 件 





package tacos.kitchen.messaging.Jms.1istener.,; 

import org.springframework.beans.factory.annotation.Autowired; 
Import org.springframework.jms.annotation.JmsListener.; 

import org.springframework.stereotype.Component; 


QComponent 


public class OrderListener { 
private kKitchenUI ui; 


QAutowired 
public OrderListener(KitchenUI ui) { 
this.ui = ui; 


} 


@JmsListener(destination = "tacocloud.order.queue") 
public void receiveOrder(Order order) { 
ui .displayOrder(order); 
} 
} 





receiveOrder() 方 法 使 用 了 JmsListener 注 解 ， 这 样 它 就 会 监听 
tacocloud.order.queue 目 的 地 的 消息 。 议 方法 不 需要 使 用 JmsTemplate， 
也 不 会 被 你 的 应 用 显 陈 调用 。 相 反 ，Spring 中 的 框 淋 代码 会 等 待 消息 抵 
达 指 定 的 目的 地 ， 当 消息 到 达 时 ，receiveOrder() 方 法 会 被 自动 调用 ， 并 
晶 会 将 消息 中 的 Order 载 荷 作为 参数 。 


从 很 多 方面 来 讲 ，@JmsListener 注 解 都 和 Spring MVC 中 的 请 求 映 射 
注解 很 相似 ， 比 如 @GetMapping 或 @PostMapping。 在 Spring MVC 中 ， 
市 有 请 求 映 射 注 解 的 方 读 会 啊 应 指定 路 径 的 请 求 。 与 之 类 似 ， 使 用 
@JmsListener 注 解 的 方法 会 对 到达 指定 目的 地 的 消 明 做 出 啊 应 。 


消 轧 监听 万 通 单 航 视 为 最 佳 选择 ， 因 为 它 不 会 导致 阻塞 ， 并 且 能 够 
快速 处 理 多 个 消息 。 但 是 在 Taco Cloud 中 ， 它 可 能 并 不 是 最 佳 的 方案 。 
在 系统 中 ， 厨 师 是 一 个 重要 的 瓶 颈 ， 他 们 可 能 无 法 在 接收 到 订单 的 时 候 
藉 即 准备 taco。 当 新 订单 出 现在 屏 攻 上 的 时 候 ， 可 能 上 一 个 订单 刚刚 完 
成 一 半 。 厨 房 用 户 寞 面 需要 在 订单 到 过时 进行 缓冲 ， 避 人 免 给 厨房 人 员 诈 
来 过 重 的 负载 。 


这 并 不 是 说 消息 监听 需 不 好 。 相 反 ， 如 果 消 息 能 够 快速 得 到 处 理 ， 
那么 它们 是 非常 适合 的 方案 。 人 但是， 如果 消 奶 处 理 妖 需要 根据 日 己 的 时 
间 请 求 更 多 消息 ， 那 么 JmsTemplate 提 供 的 拉 取 模式 会 更 加 合适 。 


JMS 坪 由 标准 Java 规 范 定义 的 ， 所 以 它 得 到 了 众多 代理 实现 的 文 
持 ， 在 Java 中 实现 消息 时 它 是 彰 见 的 可 选 方 和 案 。 但 是 JMS 有 一 些 缺 点 ， 
尤其 是 作为 Java 规 范 ， 它 只 能 用 在 Java 应 用 中 。RabbitMQ 和 Kafka 等 较 
新 的 消息 传递 方案 克服 了 这 些 缺 点 ， 可 以 用 于 JVM 之 外 的 其 他 语言 和 和 平 
台 。 让 我 们 把 JMS 放 在 一 边 ， 看 看 如 何 使 用 RabbitMQ 实 现 taco 订 单 的 消 
轧 传 递 。 


8.2 ”使 用 RabbitMQ 和 AMQP 


RabbitMQ 可 以 说 是 AMQP 最 杰出 的 实现 ， 它 提供 了 比 JMS 更 高 级 的 
消 奶 路 由 宁 略 。JMS 消 因 使 用 目的 地 名 称 来 寻 址 ， 接 收 者 要 从 这 里 检索 
消 恩 ， 而 AMQP 消 四 使 用 Exchange 和 routing key 来 寻 址 ， 这 样 消 恩 束 与 
接收 者 要 监听 的 队列 解 业 了 。Exchange 和 队列 的 关系 如 图 8.1 所 示 。 





图 8.1 发 送 到 RabbitMQ Exchange 的 消息 会 基于 routing key 和 binding 被 路 由 到 一 个 或 多 个 队列 上 


当 消 晨 抵 达 RabbitMQ 代 理 的 时 候 ， 它 会 进入 为 其 设置 的 Exchange 
上 。Exchange 负 贡 将 它 路 由 到 一 个 或 多 个 队列 中 ， 这 个 过 程 会 根据 
Exchange 的 类 型 、Exchange 和 队列 之 间 的 binding 以 及 消 居 的 routing key 
进行 路 由 。 


这 方面 有 多 个 不 同类 型 的 Exchange， 包 括 以 下 内 容 。 


。 Default: 这 是 代理 创建 的 特殊 Exchange。 它 会 将 消息 路 由 至 名 字 与 
消息 routing key 相 同 的 队列 。 上 所 有 的 队列 都 会 目 动 绑 定 全 Default 
Exchange。 

。 Direct: 如 末 消 恩 有 的 routing key 与 队列 的 binding key 相 同 ， 那 么 消息 
将 会 路 由 到 该 队列 上 。 

。 Topic: 如 果 消 息 的 routing key 与 队列 binding key《〈 可 能 会 包含 通 配 
侍 ) 匹配 ， 那 么 消息 将 会 路 由 到 一 个 或 多 个 这 样 的 队列 上 。 

。 Fanout: 不 管 routing key 和 binding key 是 人 什么， 消息 都 将 会 路 由 到 所 
有 绑 定 队列 上 。 

。 Headers: 与 Topic Exchange 类 似 ， 只 不 过 要 基于 消 姑 的 尖 信 息 进 行 
路 由 ， 而 不 是 routing key。 

。 Dead letter: 捕获 所 有 无 法 投递 《〈 也 束 是 它们 无 法 匹配 所 有 已 定义 
的 Exchange 和 队列 的 binding 关 系 ) 的 消息 。 


最 简单 的 Exchange 形 式 是 Default 和 Fanout， 因 为 它们 大 致 对 应 了 
JMS 中 的 队列 和 主题 ， 但 是 其 他 的 Exchange 人 允许 我 们 定义 更 加 灵活 的 路 
由 模式 。 


这 里 最 重要 的 是 要 明白 消息 会 通过 routing key 发 送 至 Exchange， 而 
消 明 要 在 队列 中 被 消费 。 它 们 如 何 从 Exchange 路 由 全 队列 取决 于 binding 


的 定义 以 及 哪 种 方式 最 适合 我 们 的 使 用 场景 。 


至 于 使 用 哪 种 Exchange 类 型 以 及 如 何 定 义 从 Exchange 到 队列 的 
binding， 这 本 喘 与 如 何在 Spring 应 用 中 友 送 和 接收 消息 关系 不 大 。 因 
些 ， 我 们 更 加 关心 如 何 编写 使 用 Rabbit 发 送 和 接收 消 因 的 代码 。 


注意 : 关于 如 何 绑 定 队列 到 Exchange 的 更 详细 讨论 ， 请 参考 


Alvaro Videla 和 Jason J.W. Williams 编 写 的 RabbitMQ in Action 
(Manning, 2012) 。 





8.2.1 ”添加 RabbitMQ 到 Spring 中 


在 使 用 Spring 发 送 和 接收 RabbitMQ 消 息 之 前 ， 我 们 需要 将 Spring 
Boot 的 AMQP starter 依 赖 湛 加 到 构建 文件 中 ， 和 年 换 上 文中 Artemis 或 
ActiveMQ starter 的 位 置 : 

<dependency> 


<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-amqp</artifactId> 





</dependency> 


添加 AMQP starter 到 构建 文件 中 之 后 ， 将 会 触 友 目 动 配置 功能 ， 这 
样 会 为 我 们 创建 一 个 AMQP 连 接 工 三 和 RabbitTemplate bean， 以 及 其 他 
的 一 些 支 撑 组 件 。 我 们 要 使 用 Spring 发 送 和 接收 RabbitMQ 代 理 的 消息 
只 需要 添加 这 项 依赖 加 可 以 了 。 但 是 ， 这 里 还 有 一 些 我 们 需要 营 握 的 有 


用 属性 ， 如 表 8.4 所 示 。 


表 8.4 配置 RabbitMQ 人 代理 位 置 和 和 凭证 的 属性 


on | 策 的 RabbiaMQ 人 代理 直列 


Wrens i 
玉 和 人 t 所 人 用 的 本 友和 ) 


对 于 开发 来 说 ， 我 们 可 能 会 使 用 不 需要 认证 的 RabbitMQ 代 理 ， 它 
运行 在 本 地 机 器 上 并 监听 5672 端 口 。 在 开发 阶段 ， 这 些 属性 可 能 没有 太 
大 的 用 处 ， 但 是 当 应 用 程序 投入 生产 环境 时 ， 它 们 无 疑 是 非 癌 有 用 的 。 





假设 我 们 要 将 应 用 投入 生产 环境 ，RabbitMQ 代 理 位 于 名 为 
rabbit.tacocloud.com 服 务 器 上， 监听 5673 病 口 并 且 需 要 认证 。 在 这 种 情 
况 下 ， 当 prod profile 处 于 油 活 状态 时 ，application.yml 文 件 中 的 如 下 配置 
将 会 设置 这 些 属 性 : 


spring: 
profiles: prod 


rabbitmq: 
host: rabbit.tacocloud.com 
port: 5673 
Username: tacoweb 
password: 13tm31n 





在 我 们 的 应 用 中 ，RabbitMQ 已 经 配置 好 了 ， 接 下 来 就 可 以 使 用 
RabbitTemplate 发 送 消 四 了 。 


8.2.2 ”通过 RabbitTemplate 友 达 消 忆 


Spring 对 RabbitMQ 消 妃 文 持 的 核心 是 RabbitTemplate。 
RabbitTemplate 与 JmsTemplate 类 似 ， 提 供 了 一 组 相似 的 方法 。 但 是 ， 我 
们 将 会 看 到 ， 这 里 有 一 些 细微 的 到 寞 ， 这 是 与 RabbitMQ 独 特 的 运行 方 
式 有 天 有 的。 


在 使 用 RabbitTemplate 友 送 消 轧 方 面 ， 我 们 可 以 使 用 与 JmsTemplate 
中 同名 的 send0 和 convertAndSend0) 方 法 。 但 是 ， 与 JmsTemplate 的 方法 
只 是 将 消 明 路 由 至 队列 或 主题 不 同 ，RabbitTemplate 会 按照 Exchanges 和 和 
routing key 来 友 太 消 号 。 下 和 面 列 出 关于 使 用 RabbitTemplate 友 壕 消 明 比较 
重要 的 一 些 方法 车 ; 





// 及 送 原 始 的 消息 

void send(Message message) throws AmqpException; 

void send(String routingKey, Message message) throws AmqpPEXception ; 

void send(String exchange, String routingKey, Message message) 
throws AmqpException; 


// 友 壕 根据 对 象 转换 而 成 的 消 忆 

void convertAndSend(Object message) throws AmqpException; 

void convertAndSend(String routingKey, Object message) 
throws AmqpException; 

void convertAndSend(String exchange, String routingKey, 


Object message) throws AmqpPEXception 


// 发 送 根据 对 象 转换 而 成 的 消 恩 并 且 市 有 后 期 处 理 的 功能 

void convertAndSend(Object message, MessagePostProcessor mPP) 
throws AmqpException; 

void convertAndSend(String routingKey, Object message, 
MessagePostProcessor messagePostProcessor) 
throws AmqpException; 

void convertAndSend(String exchange, String routingkey, 
Object message, 
MessagePostProcessor messagePostProcessor ) 
throws AmqpException; 





我 们 可 以 看 到 ， 这 些 方法 与 jmsTemplate 中 对 应 的 方法 遵循 了 相同 
的 模式 。 前 3 个 send(0) 方 法 都 是 发 送 诛 始 的 Message 对 象 。 接 下 来 的 3 个 
convertAndSend() 方 法 会 接受 一 个 对 象 ， 这 个 对 象 会 在 友 运 之 前 在 项 后 
转换 成 Message。 最 后 的 3 个 convertAndSend0 方 法 与 前 面 的 3 个 方法 类 
似 ， 但 是 它们 还 会 接受 一 个 MessagePostProcessor 对 象 ， 这 个 对 象 能 够 在 
Message 发 这 至 代理 之 前 对 其 进行 操作 。 


这 些 方法 与 JjmsTemplate 对 应 方法 的 不 同 之 处 在 于 ， 它 们 会 接受 
String 类 型 的 值 以 指定 Exchange 和 routing key， 而 不 像 JmsTemplate 那 样 
接 有 党 目的 地 名 称 《〈 或 Destination ) 。 没 有 接受 Exchange 参 数 的 方法 会 将 
消息 发 送 至 Default Exchange。 与 之 类 似 ， 没 有 指定 routing key 的 方法 会 
把 请 轧 路 由 全 默认 的 routing key。 


接 下 来 ， 我 们 看 一 下 如 何 使 用 RabbitTemplate 发 送 taco 订 单 。 有 一 种 
方式 是 使 用 send0 方 法 ， 如 程序 清单 8.5 所 示 。 但 是 ， 在 调用 sendO) 之 
前 ， 我 们 需要 将 Order 对 象 转换 为 Message。RabbitTemplate 能 够 通过 
getMessageConverter(0) 方 法 获取 消息 转换 器 ， 人 否则 ， 这 项 工作 会 非常 乏 
味 。 


程序 清单 8.5 ”使 用 RabbitTemplate.send0) 发 送 消息 


package tacos.messaging; 

import org.sprIngframework.amqp.core.Message 

Import org.springframework.amqp.core.MessageProperties,; 

Import org.springframework.amqp.rabbit.core.RabbitTemplate; 

Import org.SsprlIngframework.amqp.support.converter .MessageConverter ; 
import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.stereotype.Service; 

Import tacos.Order; 


QService 
public class RabbitOrderMessagingService 
ijmplements OrderMessagingService { 
private RabbitTemplate rabbit; 


QAutowired 
public RabbitOrderMessagingService(RabbitTemplate rabbit) { 
this.rabbit = rabbit; 


} 


public void sendorder(Oorder order) { 
MessageConverter converter = rabbit.getMessageConverter(); 
MessageProperties props = new MessageProperties( ) ; 
Message message = converter.toMessage(order, props); 
rabbit.send("tacocloud.order", message); 


} 





} 


有 MessageConverter 之 后 ， 将 Order 转 换 成 Message 束 是 非 沿 人 简单 
的 任务 了 。 我 们 必须 通过 MessageProperties 来 提供 消息 属性 ， 但 是 如 果 
我 们 不 需要 设置 任何 这 样 的 属性 ， 使 用 默认 的 MessageProperties 实 例 残 
可 以 了 。 随 后 ， 镜 下 的 殴 是 调用 send0 了 ， 并 将 Exchange 和 routing 
key“ 这 两 者 部 是 可 选 的 ) 连同 消息 一 起 传递 过 去 。 在 本 例 中 ， 我 们 只 
指定 了 routing key (tacocloud.order) 和 消 娠 本 里 ， 所 以 会 使 用 默认 的 


EXchange。 


这 里 提 到 了 默认 的 Exchange， 它 的 名 字 是 学 〈 空 的 String) ， 对 应 


RabbitMQ 代 理 自 动 生 成 的 Default Exchange。 与 之 相似 ， 默 认 的 routing 
key 也 是 “”( 它 的 路 由 将 会 取决 于 Exchange 以 及 相应 的 binding)〉 。 我 们 
可 以 通过 设置 spring.rabbitmq.template.exchange 和 
spring.rabbitmq.template.routing-key 属 性 重 写 这 些 默 认 值 : 


spring: 
rabbitmq: 


template: 
exchange: tacocloud.orders 
routing-key: kitchens.central 





在 本 例 中 ， 所 有 未 指明 Exchange 的 消 恩 都 将 会 目 动 发 送 至 名 为 
tacocloud.orders 的 Exchange。 如 果 在 调用 send0 或 convertAndSendO 的 时 
候 也 没有 指定 routing key， 那 么 消息 将 会 使 用 值 为 kitchens.central 的 


routing key。 


通过 消 居 转换 妖 创 建 Message 对 象 是 非常 简 蛙 的 ， 但 是 使 用 
convertAndSend0O 让 RabbitTemplate 处 理 所 有 的 转换 操作 则 会 更 加 集 单 : 


public void sendOrder(Order order) { 
rabbit.convertAndSend("tacocloud.order", order); 


} 
配置 消 轧 转换 豆 


驮 认 情 况 下 ， 消 息 转 换 是 通过 SimpleMessageConverter 来 实现 的 ， 
它 能 够 将 简单 类 型 〈 如 String) 和 Serializable 对 象 转换 成 Message 对 象 。 
但 是 ，Spring 为 RabbitTemplate 提 供 了 多 个 消息 转换 项 ， 包 括 下 面 内 容 。 


。 Jackson2JsonMessageConverter: 使 用 Jackson 2 JSON 实 现 对 象 和 


JSON 的 相互 转换 。 

MarshallingMessageConverter: 使 用 Spring 的 Marshaller 和 
Unmarshaller 进 行 转换 。 

SerializerMessageConverter: 使 用 Spring 的 Serializer 和 Deserializer 转 
换 String 和 任意 种 类 的 原生 对 象 。 


。 SimpleMessageConverter: 转换 String、 字 节 数 组 和 Serializable 关 
A 


。 ContentTypeDelegatingMessageConverter: 基于 contentType 头 信息 ， 
将 转换 蕊 能 委托 给 另外 一 个 MessageConverter。 

e。 MessagingMessageConverter: 将 消息 转换 功能 委托 给 另外 一 个 
MessageConverter， 并 将 头 信息 的 转换 委托 给 


AmdpHeaderConverter。 


如 末 需 要 变更 消息 转换 需 ， 吏 要 配置 一 个 类 型 为 MessageConverter 
的 bean。 例 如 ， 对 于 基于 JSON 的 转换 ， 我 们 可 以 按照 如 下 的 方式 来 配 


置 Jackson2JsonMessageConverter: 


QBean 
public MessageConverter messageConverter() { 


return new Jackson2JsonMessageConverter(); 





} 


Spring Boot 的 自动 配置 功能 会 发 现 这 个 bean， 并 将 它 注 入 
RabbitTemplate 中 ， 蔡 换 黑 认 的 消息 转换 夫 。 


设置 消 明 属性 


与 在 JMS 中 一 样 ， 我 们 可 能 需要 在 发 送 的 消 居 中 添加 一 些 涉 信息 
例如 ， 假 设 我 们 需要 为 所 有 通过 Taco Cloud Web 站 点 提交 的 订单 添加 一 


个 X_ORDER_SOURCE 信 息 。 在 目 行 创 建 Message 的 时 候 ， 我 们 可 以 通 
过 MessageProperties 实 例 设置 头 信息 ， 随 后 将 这 个 对 象 传 递 给 消 轧 转换 

回 到 程序 清单 8.5 的 sendOrder(0 方 法 ， 我 们 需要 做 的 项 是 添加 一 行 设 
置 头 信息 的 代码 : 


public void sendorder(Oorder order) { 
MessageConverter converter = rabbit.getMessageConverter(); 
MessageProperties props = new MessageProperties( ) ; 


props.setHeader("X_ORDER_SOURCE"”， "WEB"); 
Message message = converter.toMessage(order, props); 
rabbit.send("tacocloud.order", message); 





但 是 ， 在 使 用 convertAndSend() 的 时 候 ， 我 们 无 法 快速 访问 
MessageProperties 对 象 。 不 过 ， 此 时 MessagePostProcessor 可 以 帮助 我 
们 : 


QOverride 
public void sendOrder(Order order) { 
rabbit.convertAndSend("tacocloud.order.queue", order., 
new MessagePostProcessor() { 
QOverride 
public Message postProcessMessage(Message message) 
throws AmqpException { 
MessageProperties props = message.getMessageProperties(); 
props.setHeader("X ORDER SOURCE", "WEB"); 
return message 


} 


}); 


} 





在 这 里 ， 我 们 为 convertAndSend() 提 供 了 MessagePostProcessor 接 口 
的 匿名 内 部 类 实现 。 在 postProcessMessage() 中 ， 我 们 从 Message 中 拉 取 
MessageProperties 对 月 ， 然 后 通过 setHeader0) 方 法 设置 
又 ORDER_SOURCE 头 信息 。 


现在 ， 我 们 已 经 看 到 了 如 何 通 过 RabbitTemplate 发 送 消息 ， 接 下 来 
我 们 转换 视角 看 一 下 如 何 接收 来 自 RabbitMQ 队 列 的 消息 。 


8.2.3 ”接收 来 自 RabbitMQ 的 消息 


我 们 看 到 使 用 RabbitTemplate 发 送 消 居 与 使 用 JmsTemplate 发 送 消 忆 
并 没有 太 大 基 别 。 实 际 上 ， 接 收 来 目 RabbitMQ 队 列 的 消 居 也 与 JMS 没 有 
太 大 并 别 。 与 JMS 类 似 ， 我 们 有 两 个 可 选 方案 。 


。 使 用 RabbitTemplate 从 队列 拉 取 消息 。 
。 将 消息 推送 至 市 有 @RabbitListener 注 解 的 方法 。 


我 们 首先 看 一 下 基于 拉 取 的 RabbitTemplate.receive() 方 法 。 
使 用 RabbitTemplate 接 收 消息 


RabbitTemplate 提 供 了 多 个 从 队列 拉 取 消息 的 方法 。 其 中 ， 最 有 用 
的 方法 如 下 所 示 : 





// 接收 消 居 

Message receive() throws AmqpException; 

Message receive(String queueName) throws AmqpException,; 

Message receive(long timeoutMillis) throws AmqpException; 

Message receive(String queueName, long timeoutMillis) throws AmqpException 


2 


// 接收 由 消息 转换 而 成 的 对 象 

Object receiveAndConvert() throws AmqpException; 

Object receiveAndConvert(String queueName) throws AmqpException,; 

Object receiveAndConvert(long timeoutMillis) throws AmqpException; 

Object receiveAndConvert(String queueName, long timeoutMillis) throws 
AmqpException; 


// 接收 由 消息 转换 而 成 的 类 型 安全 的 对 象 

<T> T receiveAndConvert(ParameterizedTypeReference<T> type) throws 
AmqpException; 

<T> T receiveAndConvert(String queueName, ParameterizedTypeReference<T> ty 

pe) 
throws AmqpException; 

<T> T receiveAndConvert(long timeoutMillis, ParameterizedTypeReferencex<T> 
type) throws AmqpException,; 

<T> T receiveAndConvert(String queueName, long timeoutMillis, 
ParameterizedTypeReference<T> type) 

throws AmqpException,; 








这 些 方法 对 应 于 前 文 所 述 的 send0 和 convertAndSend0) 方 法 。send0) 
用 于 有 发送 原始 的 Message 对 象 ， 而 receiveO 则 会 接收 来 目 队 列 的 原始 
Message 对 象 。 与 之 类 似 ，receiveAndConvert() 接 收 消 晨 并 且 在 返回 之 前 
使 用 一 个 消 居 转换 强 将 它们 转换 为 领域 对 象 。 


但 是 ， 在 方法 签名 上 有 一 些 明显 的 不 同 。 背 和 完 ， 这 些 方法 都 不 会 接 
路 Exchange 和 routing key 作 为 参数 。 这 是 因为 Exchange 和 routing key 是 
用 来 将 消 居 路 由 至 队列 的 ， 在 消 因 位 于 队列 中 之 后 ， 它 们 的 目的 地 是 将 
它们 从 队列 中 拉 取 下 来 的 消 肌 者 。 消 费 销 息 的 应 用 本 吴 并 不 需要 关心 
Exchange 和 routing key。 消 费 消 恩 的 应 用 只 需要 知道 队列 信息 束 可 以 
可 过 


你 可 能 会 注意 到 ， 很 多 方法 部 接收 一 个 long 类 型 的 参数 ， 用 来 指定 
接收 消 姑 的 超时 时 间 。 默 认 情 况 下 ， 接 收 背 恩 的 超时 时 间 古 0 旱 秒 。 也 
驶 是 说 ， 调 用 receive0O 会 立即 返回 ， 如 果 没 有 可 用 消息 ， 那 么 返回 值 是 
null。 这 是 与 JmsTemplate 的 receiveO 的 一 个 显著 和 差异。 通过 传 入 一 个 超 
时 时 间 的 值 ， 我 们 就 可 以 让 receive0 和 receiveAndConvert0 阻 塞 ， 直 到 消 
恩 抵 达 或 者 超时 时 间 过 期 。 但 是 ， 即 便 我 们 设置 了 非 去 的 超时 时 间 ， 在 


代码 中 依然 要 人 处理 null 返 回 值 的 场景 。 


接 下 来 ， 我 们 看 一 下 如 何 实际 使 用 它们 。 程 序 清单 8.6 展 现 了 一 个 
新 的 基于 Rabbit 时 OrderReceiver 实 现 ， 它 使 用 RabbitTemplate 来 接收 订 
单 。 
程序 清单 8.6 ”通过 RabbitTemplate 从 RabbitMQ 中 拉 取 订单 


package tacos.kitchen.messaging.rabbit,; 

import org.springframework.amqp.core.Message.; 

import org.springframework.amqp.rabbit.core.RabbitTemplate; 

Import org.springframework.amqp.support.converter.MessageConverter.,; 
import org.springframework.beans.factory.annotation.Autowired; 
Import org.springframework.stereotype.Component,; 


QComponent 

public class RabbitOrderReceiver { 
private RabbitTemplate rabbit; 
private MessageConverter converter ; 


QAutowired 

public RabbitOrderReceiver(RabbitTemplate rabbit) { 
this.rabbit = rabbit; 
this.converter = rabbit.getMessageConverter(); 


} 


public Order receiveOrder() { 
Message message = rabbit.receive("tacocloud.orders"); 
return message != null 
? (Order) converter.fromMessage(message) 
: Null; 





所 有 的 操作 都 发 生 在 receiveOrder() 方 法 中 。 它 调用 了 注入 的 
RabbitTemplate 对 象 有 的 receive() 方 法 ， 从 名 为 tacocloud.orders 的 队列 中 拉 
取 一 个 订单 。 它 并 没有 提供 超时 人 ， 所 以 我 们 只 能 假定 这 个 调用 会 马上 
返回 ， 要 么 得 到 Message 对 象 ， 要 么 返回 null。 如 果 返 回 Message 对 象 ， 


束 使 用 RabbitTemplate 中 的 MessageConverter 将 Message 转 换 成 一 个 Order 
对 象 。 如 果 receive() 方 法 返回 null， 我 们 就 将 null 作 为 返回 值 。 


根据 使 用 场景 ， 我 们 也 许 能 够 容 仍 一 定 的 延迟 。 例 如 ， 在 Taco 
Cloud 厨 房 共 挂 的 显示 画 中 ， 如 末 没 有 订单 ， 我 们 可 以 梢 等 一 会 儿 。 假 
设 在 放弃 之 前， 我 们 决定 等 竺 30 秒 钟 ， 那 么 receiveOrder() 方 法 可 以 修改 
为 传递 30 000 坚 秒 的 延迟 给 receive0) 方 法 : 
public Order receiveOrder() { 


Message message = rabbit.receive("tacocloud.order.queue", 30606080); 
return message != null 


? (Order) converter.fromMessage(message) 
: Null; 





如 末 你 像 我 一 样 ， 澳 得 使 用 这 样 一 个 便 编 码 的 数字 会 让 人 和 觉得 不 舒 
服 ， 那 么 你 可 能 会 想 ， 创 建 一 个 市 有 @ConfigurationProperties 注 解 的 次 
并 使 用 Spring Boot 的 配置 属性 来 设置 超时 时 间 ， 可 能 会 是 更 好 的 方案 。 
在 一 点 上 ， 我 的 想法 和 你 一 样 ， 只 不 过 Spring Boot 已 经 为 我 们 提供 了 一 
个 这 样 的 配置 属性 。 如 采 你 想 要 通过 配置 来 设置 超时 时 间 ， 只 需要 在 调 
用 receive() 的 时 低 移 除 超时 值 ， 并 将 超时 时 间 人 设置 为 
spring.rabbitmq.template.receive-timeout 属 性 即 可 : 


Spring : 
rabbitmq: 


template: 
receive-timeout: 30000 





回 人 到 jreceiveOrder() 方 法 ， 我 们 必须 要 使 用 RabbitTemplate 中 的 消 虫 
转换 硕 才 能 将 传 入 的 Message 对 象 转换 成 Order 对 象 。 但 是 ， 既 然 


RabbitTemplate 已 经 携 市 了 消息 转换 左 ， 它 为 什么 不 能 目 劲 为 我 们 进行 
转换 呢 ? 这 融 是 receiveAndConvertO) 方 法 所 做 的 事情 。 信 助 
receiveAndConvert()， 我 们 可 以 将 receiveOrder() 苗 与 为 : 


public Order receiveOrder() { 


return (Order) rabbit.receiveAndConvert("tacocloud.order.queue"); 





} 


看 起 来 简 蛙 了 许多 ， 对 吧 。 唯 一 让 我 觉得 厂 烦 的 就 是 从 Object 到 | 
Order 的 类 型 转换 。 不 过 ， 这 种 转换 还 有 为 外 一 种 实现 方式 。 我 们 可 以 
传递 一 个 ParameterizedTypeReference 引 用 给 receiveAndConvert0， 这 和 样 
我 们 束 可 以 下 接 得 到 Order 对 和 象 了: 


public Order receiveOrder() { 
return rabbit.receiveAndConvert("tacocloud.order.queue", 


new ParameterizedTypeReference<Order>() {}); 





关于 这 种 方式 是 任 真 的 比 类 型 转换 更 好 ， 依 然 还 有 争论， 但 是 它 确 
实 能 够 更 加 人 确 你 类 型 安全 。 唯 一 需要 注意 的 是 ， 要 在 
receiveAndConvert() 中 使 用 ParameterizedTypeReference， 消 居 转 换 器 必 


须要 实现 SmartMessageConverter， 目 前 Jackson2JsonMessageConverter 是 


唯一 一 个 可 选 的 内 置 实现 。 


RabbitTemplate 提 供 的 拉 取 模式 适用 于 很 多 使 用 场景 ， 但 是 有 时 候 
监听 消息 并 在 消息 抵达 的 时 候 对 其 进行 处 理会 更 好 一 些 。 接 下 来 ， 我 们 
看 一 下 如 何 编写 消息 驱动 的 bean， 让 它 对 RabbitMQ 消 息 做 出 回应 。 


使 用 监听 器 处 理 RabbitMQ 的 消息 


Spring 提供 了 RabbitListener 实 现 消 妃 张 动 的 RabbitMQ bean， 对 应 于 
JmsListener。 为 了 声明 当 消 息 抵 达 RabbitMQ 队 列 时 某 个 方法 应 该 被 调 
用 ， 我 们 可 以 为 bean 的 方法 添加 @RabbitListener 注 解 。 


例如 ， 程 序 清单 8.7 展 现 了 OrderReceiver 的 RabbitMQ 实 现 ， 它 通过 
注解 声明 要 监听 订单 消 轧 ， 而 不 是 使 用 RabbitTemplate 进 行 轮 询 。 


程序 清单 8.7 将 方法 声明 为 RabbitMQ 的 消息 监听 器 


package tacos.kitchen.messaging.rabbit.1istener.,; 

Import org.springframework.amqp.rabbit.annotation.RabbitListener.,; 
import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.stereotype.Component; 


QComponent 
public class OrderListener 1{ 
private KitchenUI ui; 


QAutowired 
public OrderListener(KitchenUI ui) { 
this.ui = ui; 


} 


@QRabbitListener(queues = "tacocloud.order.queue") 
public void receiveOrder(Order order) { 
ui .displayOrder (order); 





及 现 它 与 程序 清单 8.4 的 代码 非 钊 相似 。 确 实 ， 唯 一 的 变 
更 就 是 监听 器 的 注解 ， 从 @JmsListener 换 成 了 @RabbitListener。 尺 管 
@RabbitListener 注 解 非 党 棱 ， 但 是 几乎 重复 的 代码 让 我 无 法 找 出 
GORabbitListener 具 有 什么 在 @JmsListener 中 没有 提 到 的 功能 。 当 消息 从 
各 目的 代理 推进 过 来 的 时 候 ， 这 两 个 注解 都 非 冲 适合 用 来 编写 对 应 的 代 
人 码 ， 其 中 @JmsListener 对 应 的 是 JMS 代 理 ， 而 @RabbitListener 对 应 的 是 


I 
站 
少 


RabbitMQ 代 理 。 


在 前 面 的 段落 中 ， 你 可 能 会 对 @RabbitListener 感 到 索然 无 趣 ， 但 是 
这 并 非 我 的 本 意 。 实 际 上 ，@RabbitListener 和 @JmsListener 的 运行 方式 
非常 相似 是 一 件 令 人 兴 否 的 事情 。 这 意味 看 当 我 们 使 用 RabbitMQ 蔡 代 
Artemis 或 ActiveMQ 的 时 候 ， 不 需要 学 习 全 新 的 编程 模型 。 同 样 令 人 兴 
奋 的 是 ，RabbitTemplate 和 JmsTemplate 之 则 也 具有 这 样 的 相似 性 。 


让 我 们 暂且 你 持 一 下 这 种 兴奋 ， 在 本 草 结 束 之 前 ， 我 们 看 一 下 
Spring 文 持 的 男 外 一 个 消 居 方 采 : Apache Kafka。 


8.3 ”使 用 Kafka 的 消息 


Apache Kafka 十 我 们 在 本 和 章 研 究 的 最 新 的 消息 方案 。 乍 看 上 去 ， 
Kafka 是 与 ActiveMQ、Artemis 或 Rabbit 奖 似 的 消息 代理 ， 其 实 Kafka 有 一 
些 独特 的 技巧 。 


Kafka 设 计 为 集群 运行 ， 从 而 能 够 实现 很 强 的 可 扩展 性 。 通 过 将 主 
题 在 集群 的 所 有 实例 上 进行 分 区 (partition) ， 它 能 够 具有 更 强 的 弹 
性 。RabbitMQ 主 要 处 理 Exchange 中 的 队列 ， 而 Kafka 仅 使 用 主题 实现 消 
轧 的 及 布 /订阅 。 


Kafka 主 题 会 复制 到 集群 的 所 有 代理 上 。 集 群 中 的 每 个 市 点 部 会 担 
任 一 个 或 多 个 主题 的 首领 (leader) ， 负 责 该 主题 的 数据 并 将 其 复制 到 
集群 中 的 其 他 市 点 上 。 


更 进一步 来 讲 ， 每 个 主题 可 以 划分 为 多 个 分 区 。 在 这 种 情况 下 ， 集 
群 中 的 每 个 节 氮 是 东 个 主题 一 个 或 多 个 分 区 的 首领 ， 但 并 不 是 整个 主题 
的 首领 。 主 题 的 贡 任 会 在 所 有 节 氮 间 进 行 拆 分 。 图 8.2 阐 述 了 它 是 如 何 
运行 的 。 


Kafka 集 和 群 


和 





图 8.2 ”Kafka 集 群 是 由 多 个 代理 组 成 的 ， 每 个 代理 作为 主题 分 区 的 首领 


天 于 Kafka 的 独特 染 构 ， 我 建议 你 阅读 Dylan Scott 编写 的 Kajfka in 
Action (Manning，2017〉。 束 我 们 来 讲 ， 我 们 将 会 关注 如 何 通 过 Spring 
发 送 和 接收 Kafka 的 消息 。 


8.3.1 为 Spring 搭建 支持 Kafka 消 息 的 环境 


为 了 搭建 Kafka 的 消 恩 环境， 我 们 需要 添加 对 应 的 依赖 到 构建 文件 
中 。 但 是 ， 与 JMS 和 RabbitMQ 方 案 不 同 ， 并 没有 针对 Kafka 的 Spring 
Boot starter。 不 过 ， 不 用 担心 ， 我 们 只 需要 添加 一 项 依赖 : 


| <dependency> 


<grFoupId>org.springframework.kafka</groupId> 
<artifactId>spring-kafka</artifactId> 
</dependency> 


这 项 依赖 会 为 我 们 的 项 目 引 入 Kafka 所 需 的 所 有 内 容 。 男 外 ， 它 的 
出 现 会 触发 Spring Boot 对 Kafka 的 自动 配置 ， 除 了 其 他 功能 之 外 ， 它 会 
在 Spring 应 用 上 下 文中 创建 一 个 KafkaTemplate。 我 们 所 需要 做 的 束 古 注 
入 KafkaTemplate 并 使 用 它 来 发 布 和 接收 消 忆 。 


但 是 ， 在 友 壕 和 接收 消 恩 之 前 ， 我 们 还 需要 注意 使 用 Kafka 时 的 一 
些 属 性 。 具 体 来 讨 ，KafkaTemplate 默 认 会 使 用 localhost 上 监 昕 9092 六 口 
的 Kafka 人 代理。 在 开 友 应 用 的 时 候 ， 在 本 地 局 动 Kafka 代 理 没 有 问题 ， 但 
尽 在 投入 生产 的 时 候 ， 我 们 需要 配置 不 同 的 主机 和 端口 。 


spring.kafka.bootstrap-servers 属 性 能 够 设置 一 个 或 多 个 Kafka 服 务 器 
的 地 址 ， 系 统 将 会 使 用 它 来 建立 到 Kafka 集 群 的 初始 连接 。 例 如 ， 集 和 群 
中 的 某 个 服务 器 运行 在 kafka.tacocloud.com 上 并 监听 9092 端 口 ， 那 么 我 
们 可 以 投 照 如 下 的 方式 在 YAML 中 配置 它 的 位 置 : 


Spring : 
kafka: 


bootstrap-servers: 
- kafka.tacocloud.com:90692 





Y 一 


但 是 需要 注意 spring.kafka.bootstrap-servers 是 复数 形式 ， 它 能 接受 一 


个 列表 。 所 以 ， 我 们 可 以 提供 集群 中 的 多 个 Kafka 服 务 右 : 





spring: 
kafka: 
bootstrap-servers: 
- kafka.tacocloud.com:90692 
- kafka.tacocloud.com:90693 


| - kafka.tacocloud.com:90694 | 


Kafka 在 项 目 中 准备 束 弹 之 后 ， 我 们 束 可 以 肥 这 和 接收 消 明 了。 我 
们 首先 使 用 KafkaTemplate 发 送 Order 对 象 人 天 Kafka 中 。 


8.3.2 ”通过 KafkaTemplate 发 送 消息 


在 很 多 方面 ，KafkaTemplate 与 JMS 和 RabbitMQ 对 应 的 模板 非常 相 
似 。 但 同时 ， 它 也 有 很 大 的 差异 。 在 发 送 消 息 的 时 候 ， 这 一 点 非常 明 


志 : 


Listenab1leFuture<SendResult<K，V>> send(String topic, V data); 
ListenableFuture<SendResult<Kk, V>> send(String topic, K key, V data); 
ListenableFuture<SendResult<Kk, V>> send(String topic, 

Integer partition, K key, V data); 
ListenableFuture<SendResult<Kk, V>> send(String topic, 

Integer partition, Long timestamp, K key, V data); 
ListenableFuture<SendResult<K, V>> send(ProducerRecord<Kk, V> record); 
ListenableFuture<SendResult<Kk, V>> send(Message<?> message ) ; 


Listenab1leFuture<SendResult<K，V>> sendDefault(V data ) ; 
ListenableFuture<SendResult<Kk, V>> sendDefault(K key, V data); 
ListenableFuture<SendResult<Kk, V>> sendDefault(Integer partition, 
K key, V data); 
ListenableFuture<SendResult<Kk, V>> sendDefault(Integer partition, 
Long timestamp, K key, V data); 





我 们 首先 可 能 会 发 现 ， 这 里 没有 convertAndSend0 方 法 了 。 这 
为 ，KafkaTemplate 是 通过 泛 型 类 型 化 的 ， 在 及 送 消息 的 时 候 ， po 
直接 处 理 领 域 类 型 。 这 样 的 话 ， 所 有 的 send0) 方 法 都 完成 了 
convertAndSend() 的 任务 。 


你 可 能 也 会 发 现 ，send0 和 sendDefaultO 的 参数 与 JMS 和 Rabbit 有 很 


大 的 短 民 。 在 使 用 Kafka 及 送 消息 的 时 候 ， 我 们 可 以 使 用 如 下 参数 设置 
消息 访 如 何 进 行 及 送 : 

e。 消 县 要 及 送 到 的 主题 (send0) 方 法 的 必 选 参数 ) : 

。 主题 要 与 入 的 分 区 《可 选 ) ; 

。 刀 了 床上 要 友 送 的 key (可 选 ); 

。 时 间 惟 〈 可 选 ， 默 认为 System.currentTimeMillisO ) : 

。 载 何 〈 必 选 ) 。 


主题 和 载 傈 是 其 中 最 重要 的 两 个 参数 。 分 区 和 key 对 于 如 何 使 用 
KafkaTemplate 几 乎 没有 影响 ， 只 是 作为 额外 的 信息 提供 给 send0 和 
sendDefault()。 对 于 我 们 的 场景 来 说 ， 我 们 只 关心 将 消 恩 载 傈 友 友 到 给 
定 的 主题 ， 不 用 担心 分 区 和 key 的 问题 。 


对 于 send() 方 法 来 说 ， 我 们 还 可 以 选择 发 一 个 ProducerRecord 对 
象 ， 它 只 是 一 个 人 简单 类 型 ， 将 上 述 的 参数 放 到 了 一 个 对 象 中 。 我 们 还 可 
以 发 迹 Message 对 象 ， 但 是 需要 将 领域 对 象 转换 成 Message 对 象 。 相 对 创 


建 和 发 送 ProducerRecord 和 Message 对 象 ， 使 用 其 他 的 方法 会 更 价 单 一 
些 。 


信 助 KafkaTemplate 及 其 send0 方 法 ， 我 们 可 以 编写 一 个 基于 Kafka 实 
现 的 OrderMessagingService 实 现 。 程 序 清单 8.8 展 现 了 该 实现 类 。 


程序 清单 8.8 ”使 用 KafkaTemplate 发 送 订单 





package tacos.messaging; 

Import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.kafka.core.KafkaTemplate; 

import org.springframework.stereotype.Service; 


QService 
public class KafkaOrderMessagingService 
ijmplements OrderMessagingService { 
private KafkaTemplate<String, Order> kafkaTemplate,; 
QAutowired 
public KafkaOrderMessagingServicel 


KafkaTemplate<String, Order> kafkaTemplate) { 
this.kafkaTemplate = kafkaTemplate; 


} 


QOverride 
public void sendorder(Oorder order) { 
kafkaTemplate.send("tacocloud.orders.topic", order); 


} 


在 这 个 OrderMessagingService 的 新 实现 中 ，sendOrderO 用 到 了 注入 
的 KafkaTemplate 对 象 的 send0 方 法 ， 将 Order 发 送 到 名 为 
tacocloud.orders.topic 的 主题 中 。 除 了 代码 中 随处 可 见 的 “Kafka” 之 外 ， 
它 其 实 与 为 JMS 和 Rabbit 编 写 的 代码 并 没有 太 大 的 差 卉 。 


如 果 你 想 要 设置 默认 主题 ， 那 么 可 以 稍微 简化 一 下 sendOrder()。 首 
先 ， 通 过 spring.kafka.template.default-topic 属 性 ， 我 们 可 以 将 默认 主题 设 


置 为 tacocloud.orders.topic: 


spring: 
kafka: 


template: 
default-topic: tacocloud.orders.topic 





然后 ， 在 sendOrder() 方 法 中 ， 我 们 就 可 以 调用 sendDefaultO 而 不 古 
send() 了 ， 这 样 可 以 不 用 指定 主题 的 名 称 : 


|eoverride 


public void sendorder(Oorder order) { 
kafkaTemplate.sendDefault (order); 
} 


现在 ， 我 们 已 经 编写 完 发 送 消息 的 代码 了 。 接 下 来 ， 我 们 转移 一 下 
注意 力 ， 编 写 从 Kafka 中 接收 消息 的 代码 。 


8.3.3 ”编写 Kafka 监 听 器 


除了 send() 和 sendDefault0 特 有 的 方法 签名 之 外 ，KafkaTemplate 与 
JmsTemplate 和 RabbitTemplate 男 一 个 不 同 之 处 在 于 它 没 有 提供 接收 消息 
的 方法 。 这 意味 看 在 Spring 中 想 要 消费 来 日 Kafka 主 题 的 消 居 只 有 有 一 种 办 
法 ， 就 是 编写 消 恩 监 昕 疾 。 

对 于 Kafka 消 恩 玉 说 ， 消 居 监 听 右 是 骨 过 市 有 @KafkaListener 注 解 的 
方法 来 实现 的 。@KafkaListener 大 致 对 应 于 @JmsListener 和 


@RabbitListener， 并 且 使 用 方式 也 基本 相同 。 如 下 的 程序 清单 展示 了 为 
Kafka 编 写 的 其 于 监 昕 器 的 订单 接收 闫 。 


程序 清单 8.9 ”使 用 @KafkaListener 接 收 订 单 





package tacos.kitchen.messaging.kafka.1istener.,; 

Import org.springframework.beans.factory.annotation.Autowired; 
Import org.springframework.kafka.annotation.KafkaListener; 
import org.springframework.stereotype.Component; 

Import tacos.Order; 

Import tacos.kitchen.KitchenUI; 

QComponent 

public class OrderListener 1{ 


private KitchenUl ui; 


QAutowired 


public OrderListener(KitchenUI ui) { 
this.ui = ui; 


} 


@KafkaListener(topics="tacocloud.orders.topic") 
public void handle(Order order) { 
ui .displayOrder (order); 


} 





handle0 方 法 使 用 了 Q@KafkaListener 注 解 ， 表 明 当 有 消息 抵达 名 为 
tacocloud.orders.topic 的 主题 时 ， 访 方法 将 会 被 调用 。 如 程序 清单 8.9 所 
示 ， 我 们 只 将 Order( 载 傈 对象 传 递 给 了 handle()。 如 果 你 想 要 获取 消 
居中 其 他 的 元 数据 ， 我 们 也 可 以 接受 ConsumerRecord 或 Message 对 象 。 


例如 ， 如 下 的 handle0 实 现 接受 一 个 ConsumerRecord， 这 样 我 们 束 
能 在 日 志 中 将 消息 的 分 区 和 时 间 惟 记录 下 来 : 


@KafkaListener(topics="tacocloud.orders.topic") 
public void handle(Order order, ConsumerRecord<Order> record) { 
log.info("Received from partition {} with timestamp {}",， 


record.partition(), record.timestamp()); 
ui .displayOrder (order); 


} 





类 似 地 ， 我 们 还 可 以 用 一 个 Message 对 象 来 符 代 ConsumerRecord， 
并 且 能 够 达到 相同 的 目的 : 


@KafkaListener(topics="tacocloud.orders.topic") 

public void handle(Order order, Message<Order> message) { 

MessageHeaders headers = message.getHeaders( ) ; 
log.info("Received from partition {} with timestamp {}",， 


headers.get(KafkaHeaders .RECEIVED PARTITION ID) 
headers.get(KafkaHeaders .RECEIVED TIMESTAMP)); 
ui .displayOrder (order); 


} 





值得 一 提 的 是 ， 消 息 载 倚 也 可 以 通过 ConsumerRecord.value0) 或 
Message.getPayload0 获 取 到 。 这 意味 看 我 们 可 以 通过 这 些 对 象 获取 
Order， 而 不 必 和 直接 将 其 作为 handle() 的 参数 。 


8.4 ”小 结 


。 措 步 消 居 在 要 通信 的 应 用 程序 之 则 提供 了 一 个 中 间 层 ， 这 样 能 够 实 
现 更 松散 的 契合 和 更 强 的 可 扩展 性 。 

。 Spring 支持 使 用 JMS、RabbitMQ 或 Apache Kafka 实 现 异步 消息 。 

。 应 用 程序 可 以 使 用 基于 模板 的 客户 着 〈JmsTemplate、 

RabbitTemplate 或 KafkaTemplate) 辐 消 息 代 理发 送 消息 。 

接收 消 奶 的 应 用 程序 可 以 什 助 相同 的 基于 模板 的 客户 问 以 拉 取 模式 

消费 消 妃 。 

通过 使 用 消息 监听 器 注解 〈@JmsListener、@RabbitListener 或 

@KafkaListener) ， 消 息 也 可 以 推送 至 消费 者 的 bean 方 法 中 。 





[1] 这 些 方法 是 由 AmqpTemplate 定 义 的 ，RabbitTemplate 实 现 了 诅 接 
面相 


第 9 章 ”Spring 集 成 


实时 处 理 数 据 


定义 集成 流 


使 用 Spring Integration 的 Java DSL 定 义 


与 Email、 文 件 系统 和 其 他 外 部 系统 进行 集成 





在 旅行 时 ， 最 让 我 感到 泪 供 的 一 件 事 束 是 长 途 飞 行 时 的 互联 网 连接 
非常 过， 或 者 根本 融 没 有 。 我 喜欢 利用 空中 时 间 完 成 一 些 工 作 ， 这 本 书 
的 很 多 内 容 束 是 这 样 写 出 来 的 。 但 是 ， 如 果 没 有 网 络 连接 ， 恰 好 我 义 想 
获取 菏 个 库 或 者 但 看 一 个 JavaDoc 文 档 ， 那 么 我 就 无 能 为 力 了 。 因 此 ， 
我 现在 会 随身 市 一 本 书 ， 以 便于 在 这 种 场合 下 阅读 。 

束 像 我 们 需要 连接 互联 网 才能 提高 生产 效率 一 样 ， 很 多 应 用 都 需要 
连接 外 部 系统 才能 完成 它们 的 功能 。 应 用 程序 可 能 需要 读 取 或 友 达 
Email、 与 外 部 API 区 互 或 者 对 写 入 数据 库 的 数据 做 出 反应 。 而 且 ， 由 于 


数据 古 在 外 部 系统 读 取 或 与 入 的 ， 应 用 可 能 需要 以 东 种 方式 处 理 这 些 数 
据 ， 这 样 才 能 转换 为 应 用 程序 目 己 的 领域 闫 。 


在 本 章 中 ， 我 们 将 会 看 到 如 何 使 用 Spring Integration 实 现 通 用 的 集 
成 模式 。Spring Integration 是 众多 集成 模式 的 现成 实现 ， 这 些 模式 在 
Gregor Hohpe 和 Bobby Woolf 编 写 的 《企业 集成 模式 》 (Enterprise 
Integration Patterns，Addison-Wesley，2003) 中 进行 了 归 类 。 每 个 模式 
都 实现 为 一 个 组 件 ， 消 息 会 通过 该 组 件 在 管道 中 传递 数据 。 借 助 Spring 
配置 ， 我 们 可 以 将 这 些 组 件 组 疹 成 一 个 党 过， 数据 可 以 通过 这 个 管道 来 
流动 。 我 们 从 定义 一 个 简单 的 集成 流 开 始 ， 这 个 流 包 含 了 Spring 
Integration 的 众多 特性 和 特点 。 


9.1 声明 一 个 窗 单 的 集成 流 


通常 来 讨 ， 在 使 用 Spring Integration 创 建 集成 流 时 ， 是 通过 声明 一 
个 应 用 程序 能 够 接收 或 友 壕 哪些 数据 到 应 用 程序 之 外 的 资源 来 实现 的 。 
应 用 程序 可 能 集成 的 资源 之 一 驳 是 文件 系统 。 因 此 ，Spring Integration 
的 很 多 组 件 都 有 谈 入 和 与 入 文件 的 通道 适 配 套 (channel adapter) 。 


为 了 熟悉 Spring Integration， 我 们 将 会 创建 一 个 集成 流 ， 这 个 流 会 
与 入 数据 到 文件 系统 中 。 首 先 ， 我 们 需要 这 加 Spring Integration 到 项 目 
的 构建 文件 中 。 对 于 Maven 构 建 来 讲 ， 必 要 的 依 顿 如 下 所 示 : 





<dependency> 
<grouplId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-integration</artifactId> 
</dependency> 


<dependency> 
<grouplId>org.springframework.integration</groupId> 
<artifactId>spring-integration-file</artifactId> 
</dependency> 





第 一 项 依赖 是 Spring Integration 的 Spring Boot starter。 不 党 我 们 与 哪 
种 流 进行 交互 ， 对 于 Spring Integration 流 的 开发 来 讲 ， 这 个 依赖 都 是 必 
需 的 。 与 所 有 的 Spring Boot starter 一 样 ， 在 Initializr 表 单 中 ， 这 个 依赖 也 


可 以 通过 复 选 框 进行 选择 。 


第 二 项 依赖 是 Spring IPmtegration 的 文件 病 点 模 芯 。 这 个 模 喘 是 与 外 
部 系统 集成 的 二 十 多 个 柑 块 之 一 。 我 们 会 在 9.2.9 小 节 中 更 加 评 细 地 讨论 
闹 反 模块 。 对 于 现在 来 讲 ， 我 们 只 需要 知道 文件 六 后 模 块 据 供 了 将 文件 
从 文件 系统 导入 集成 流 和 /或 将 流 中 的 数据 号 入 文件 系统 的 能 力 即 可 。 


接 下 来 ， 我 们 需要 为 应 用 创建 一 种 方法 ， 让 它 能 够 肥 达 数据 到 集成 
沈 中 ， 这 样 它 才 能 写 入 到 文件 中 。 为 了 实现 这 一 点 ， 我 们 需要 创建 一 个 
网 天 接口 ， 这 样 的 网 关 接 口 如 程序 清早 9.1 所 示 。 





程序 清单 9.1 将 方法 调用 转换 成 消息 的 消 恩 网 天 接口 


package sia5; 

Import org.springframework.integration.annotation.MessagingGateway; 
import org.springframework.integration.file.FileHeaders,; 

import org.springframework.messaging.handler.annotation.Header; 


@QMessagingGateway (defaultRequestChannel="textInChannel") 
消 忆 网 天 


public interface FileWriterGateway { 


void writeToFile( 


@Header (FileHeaders.FILENAME) String filename, 一 --- 写 入 文件 
String data); 





尽 党 这 只 是 一 个 很 简单 的 Java 接 口 ， 但 是 FileWriterGateway 有 很 多 
东西 需要 介绍 。 我 们 首先 看 到 的 是 ， 它 使 用 了 @MessagingGateway 注 
解 。 这 个 注解 会 告诉 Spring Integration 要 在 运行 时 生成 该 接口 的 实现 ， 

这 与 Spring Data 在 运行 时 生成 repository 接 口 的 实现 非常 类 似 。 其 他 地 方 
的 代码 在 布 望 号 入 文件 的 时 候 将 会 调用 它 。 


@MessagingGateway 的 ep 属性 表明 接口 方法 调用 
时 所 返回 的 消 明 要 发 运 全 给 定 的 消 居 通道 (message channel) 。 在 本 例 
中 ， 我 们 声明 调用 writeToFileO) 所 形成 的 消 恩 应 该 发 送 至 名 为 
textInChannel 的 通道 中 。 


对 于 writeToFile() 方 法 来 说 ， 它 以 String 类 型 的 形式 接受 一 个 文件 
名 ， 男 外 一 个 String 包 含 了 要 写 入 文件 中 的 文本 。 大 于 这 个 方法 的 釜 
名 ， 还 需要 注意 filename 参 数 上 市 有 @Header。 在 本 例 中 ，@Header 广 解 
表明 传递 给 他 ename 的 值 应 该 包含 在 消 恩 头 信 息 中 (通过 
FileHeaders.FILENAME 声 明 ， 它 将 会 被 解析 成 fle_name)〉 ， 而 不 是 放 到 
消 明 载 何 (payload) 中 。 


现在 ， 我 们 已 经 有 了 消 奶 网 天 ， 接 下 来 束 需 要 配置 集成 流 了 。 人 尺 管 
我 们 往 构 建文 件 中 这 加 的 Spring Integration starter 依 赖 能 够 月 用 Spring 
Integration 的 目 动 配置 功能 ， 但 是 满足 应 用 项 求 的 法 定义 则 需要 我 们 目 
行 编写 额外 的 配置 。 在 声明 集成 流 方 面 ， 我 们 有 3 种 配置 方案 可 供 选 
择 : 


。 XML 了 配置; 
e。 Java 配 置 ; 


。 使 用 DSL 的 Java 配 置 。 


我 们 会 依次 看 一 下 Spring Integration 的 这 3 种 配置 风格 ， 首 先 从 较 
为 老式 的 XML 配 置 开始 。 


9.1.1 使 用 XML 定 义 集成 流 


尽管 在 本 书 中 ， 我 尽量 避免 使 用 XML 配 置 ， 但 是 Spring Integration 
有 使 用 XML 定 义 集成 流 的 漫长 历史 。 所 以 ， 我 认为 至 少 展现 一 个 XML 
定义 集成 流 的 样 例 还 是 很 有 价值 的 。 程 序 清单 9.2 展 现 了 如 何 使 用 XML 
配置 示例 集成 流 。 


程序 清单 9.2 使 用 Spring XML 配置 定义 集成 流 


<?xml] version="1.60" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:xsi="http://www.w3.org/2601/XMLSchema-instance”" 
xmlns:int="http://www.springframework.org/schema/integration" 
xmlns:int-file="http://www.springframework.org/schema/integration/file" 
xsi:schemaLocation="http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans.xsd 
http://www.springframework.org/schema/integration 
http://www.springframework.org/schema/integration/spring-integration.x 
sd 
http://www.springframework.org/schema/integration/file 
http://www.springframework.org/schema/integration/file/spring-integrat 
1on- 
file.xsd"> 
<int:channel id="textInChannel” /> 一 --- 声明 textInChannel 
<int:transformer 1Id= upperCase - 
input-channel="textInChannel" 
output-channel="fileWriterChannel" 


expression="payload.toUpperCase()" /> 一 --- 转换 文本 


<int:channel id="fileWriterChannel™” /> 一 --- 声明 fileNriterC 


hannel 


<int-file:outbound-channel-adapter id="writer" 
channel="fileWriterChannel" 
directory="/tmp/siaS/files" 
mode="APPEND" 
append-new-line="true" /> 一 --- 将 文本 写 入 到 文件 中 


</beansy> 





我 们 将 程序 清单 9.2 中 的 XML 拆 分 讲解 一 下 。 


。 我 们 首先 配置 了 一 个 名 为 textInChannel 的 通道 。 你 会 发 现 ， 它 就 是 
FileWriterGateway 的 请 求 通道 。 当 FileWriterGateway 的 writeToFileO) 
方法 航 调 用 的 时 候 ， 结 果 形 成 的 消息 将 会 及 布 到 这 个 通道 上 。 

。 我 们 还 配置 了 一 个 转换 器 (transformer) ， 它 会 从 textInChannel 接 
收 消息 。 它 使 用 Spring 表达 式 语 言 (Spring Expression Language， 
SpEL ) 为 消息 载 答 调用 了 toUpperCase() 方 法 。 进 行 大 写 操 作 之 后 的 
结果 会 发 布 到 fileWriterChannel 上 。 

。 上 逢 后 ， 我 们 配置 了 名 为 亿 eWriterChannel 的 通道 。 这 个 通道 会 作为 
一 个 导线 ， 将 转换 占 与 出 站 通道 适 配 费 (outbound channel 
adapter) 连接 在 一 起 。 

。 最 后 ， 我 们 使 用 intfile 命 名 空间 配置 了 出 站 通道 适 配 右 。 这 个 XML 
命名 空间 是 由 Spring Integration 的 文件 模块 提供 的 ， 实 现 文 件 写 入 
的 功能 。 按 照 我 们 的 配置 ， 它 从 fileWwriterChannel 接 收 消 息 ， 并 将 
兴 县 的 载 傈 写 入 到 一 个 文件 中 ， 这 个 文件 的 名 称 是 由 消 居 头 信 息 中 
的 file_name 属 性 指定 的 ， 而 存 入 的 目录 则 是 由 这 里 的 directory 属 性 
指定 的 。 如 果 文 件 已 经 存在 ， 那 么 文件 内 容 会 以 新 行 的 方式 进行 退 
加 ， 而 不 是 宪 荔 该 文件 。 


图 9.1 使 用 《企业 集成 模式 》 中 的 图 形 元 系 样 式 曾 述 了 这 个 流 。 








文件 写 入 髓 网 关 通道 中 的 文本 写 转换 名 文件 写 入 器 通道 文件 出 站 通道 适配器 


图 9.1 文件 写 入 占 的 集成 流 


如 果 想 要 在 Spring Boot 应 用 中 使 用 XML 配置 ， 那 么 我 们 需要 将 
XML 作为 资源 寻 入 到 Spring 应 用 中 。 节 简单 的 实现 方式 焉 是 在 应 用 的 未 
个 Java 配 置 类 上 使 用 Spring 的 @ImportResource 注 解 : 


@Configuration 


@ImportResource("classpath:/filewriter-config.xml") 
public class FileWriterIntegrationConfig { ... } 





尽管 基于 XML 的 配置 能 够 很 好 地 用 于 Spring Integration， 但 是 大 多 
数 的 开 肥 人员 对 于 XML 的 使 用 越 来 越 讶 导 。“《 正 如 我 所 言 ， 在 本 书 
中 ， 我 会 尽量 避免 使 用 XML 配置 。) 现在 ， 我 们 抛 开 这 些 尖 括号 ， 看 
一 下 Spring Integration 的 Java 配 置 风 格 。 


9.1.2 ”使 用 Java 配 置 集成 流 


大 多 数 的 现代 Spring 应 用 程序 都 会 避免 使 用 XML 配置 ， 而 更 加 青 上 时 
Java 配 置 。 实 际 上 ， 在 Spring Boot 心 用 中 ，Java 配 置 是 目 动 化 配置 功能 
更 目 然 的 补充 形式 。 因 此 ， 如 宁 我 们 要 为 Spring Boot 应 用 添加 集成 流 ， 
最 好 使 用 Java 来 定义 流程 。 


程序 消音 9.3 展 示 了 使 用 Java 配 置 编写 集成 流 的 一 个 样 例 。 这 里 的 代 
但 依然 是 功能 相同 的 文件 与 入 集成 演 ， 但 是 这 次 我 们 选择 使 用 Java 来 实 


现 。 
程序 清单 9.3 ”使 用 Java 配 置 来 定义 集成 流 


package sia5; 

import JjJava.io.File; 

Import org.springframework.context.annotation.Bean; 

Import org.springframework.context.annotation.Configuration; 

Import org.springframework.integration.annotation.ServiceActivator.,; 
import org.springframework.integration.annotation.Transformer; 

import org.springframework.integration.file.FileWritingMessageHandler.; 
Import org.springframework.integration.file.support.FileExistsMode; 
import org.springframework.integration.transformer.GenericTransformer.; 


@Configuration 
public class FileWriterIntegrationConfig { 


QBean 
@Transformer(inputChannel="textInChannel", 一 --- 声明 转换 规 
outputChannel="fileWriterChannel") 


public GenericTransformer<String, String> upperCaseTransformer() { 
return text -> text.toUpperCase( ) ; 


} 


QBean 
QServiceActivator(inputChannel="fileWriterChannel") 
public FileWritingMessageHandler fileWriter() 1 一 --- 声明 文件 与 
入 全 
FileWritingMessageHandler handler = 
new FileWritineMessageHandler(new File("/tmp/sia5/files")); 
handler. setExpectReply(false); 
handler.setFileExistsMode(FileExistsMode.APPEND); 
handler .setAppendNewLine(true); 
return handler; 





在 Java 配 置 中 ， 我 们 声明 了 两 个 bean: 一 个 转换 器 ， 还 有 一 个 文件 
写 入 的 消息 处 理 右 。 这 里 的 转换 货 是 GenericTransformer。 因 广 
GenericTransformer 古 一 个 水 数 式 接口 ， 所 以 我 们 可 以 使 用 lambda 表 达 式 
为 其 提供 实现 ， 这 里 调用 了 消 晨 文本 的 toUpperCase() 方 法 。 转 换 疾 bean 


使 用 了 @Transformer 注 解 ， 这 样 会 将 其 声明 成 集成 流 中 的 一 个 转换 桥 
它 接 受 来 日 textInChannel 通 甫 的 消 轧 ， 然 后 将 消 恩 写 入 到 名 为 
fileWriterChannel 的 通道 中 。 


负 贡 文件 写 入 的 bean 则 使 用 了 @ServiceActivator 注 解 ， 表 明 它 会 接 
党 来 目 fleWriter Channel 的 消 轧 ， 并 且 会 将 消息 传递 给 
FileWritingMessageHandler 实 例 所 定义 的 服务 。 
FileWritingMessageHandler 是 一 个 消 因 处 理 右 ， 它 会 将 消 明 的 载 何 写 入 
特定 目录 的 一 个 文件 中 ， 而 文件 的 名 称 有 是 通过 消 轧 的 fle_name 头 信息 指 
定 的 。 与 XML 样 例 类 似 ，FilewritingMessageHandler 也 配置 为 以 新 行 的 

方式 为 文件 退 加 内 容 。 


ork bean 的 一 个 独特 之 处 在 于 它 调 用 了 
setExpectReply(false) 方 法 ， 这 个 方法 能 够 告知 服务 油 活 占 (service 
activator) 不 pe 甬道 (reply channel， 通 过 这 样 的 通道 ， 我 
们 可 以 将 菜 个 值 返 回 到 流 中 的 上 游 组 件 ) 。 如 果 我 们 不 调用 
setExpectReplyO0， 文 件 写 入 bean 的 默认 值 是 true。 尽 管 管道 的 功能 和 预 
期 一 样 ， 但 是 在 日 志 中 会 看 到 一 些 错误 日 志 ， 提 示 我 们 没有 设置 答复 通 

我 们 在 这 里 没有 几 要 显 式 声明 通道 。 如 有 果 名 为 textInChannel 和 
fileWriterChannel 的 bean 不 存在 ， 那 么 这 两 个 通道 将 会 自动 创建 。 但 是 ， 


如 果 你 想 要 更 加 精确 地 控制 通道 配置 ， 那 么 可 以 按照 如 下 的 方式 显 式 构 
建 这 些 bean: 


|@Bean ] 


public MessageChannel textInChannel() { 
return new DirectChannel(); 


} 


QBean 
public MessageChannel fileWriterChannel() { 
return new DirectChannel(); 


} 





基于 Java 的 配置 方案 可 能 会 更 易于 阅读 ， 也 更 加 人 简洁， 而 且 符 合 我 
在 本 书 中 倡导 的 纯 Java 配 置 风 格 。 但 是 ， 使 用 Spring Integration 的 Java 
DSL (Domain-Specific Language， 领 域 特 定语 言 ) 配置 风格 的 话 ， 它 可 
以 更 加 流畅 。 


9.1.3 ”使 用 Spring Integration 的 DSL 配 置 


我 们 绸 次 符 试 一 下 文件 号 入 集成 流 的 定义 。 这 一 次 ， 我 们 依然 使 用 
Java 进 行 定 义 ， 但 是 会 使 用 Spring Integration 的 Java DSL。 这 一 次 我 们 不 
再 将 激 中 的 每 个 组 件 都 声明 为 单独 的 bean， 而 是 使 用 一 个 bean 来 定义 整 
个 流 ， 如 程序 清单 9.4 所 示 。 


程序 清单 9.4 ”为 集成 流 的 设计 提供 一 个 流畅 的 API 





package sia5; 

import JjJava.io.File; 

Import org.springframework.context.annotation.Bean; 

import org.springframework.context.annotation.Configuration; 

Import org.springframework.integration.dsl.IntegrationFlow; 

import org.springframework.integration.dsl.IntegrationFlows; 

Import org.springframework.integration.dsl.channel.MessageChannels; 
import org.springframework.integration.file.dsl.Files,; 

Import org.springframework.integration.file.support.FileExistsMode; 


@Configuration 


public class FileWriterIntegrationConfig { 


QBean 
public IntegrationFlow fileWriterFlow() { 
return IntegrationFlows 
.from(MessageChannels.direct("textInChannel")) 一 --- 入 站 通道 
.<String, String>transform(t -> t.toUpperCase()) 一 --- 声明 转换 


万 
五 


.handle(Files 一 --- 处 理 文件 写 


> 


.OUtboundAdapter(new File("/tmp/sia5/files")) 
.fileExistsMode(FileExistsMode.APPEND) 
.appendNewLine(true)) 

.get(); 





这 种 配 兽 方式 在 一 个 bean 方 法 中 定义 了 整个 流 ， 己 经 做 到 了 尺 可 能 
人 简洁 。Integration Flows 关 初始 化 构建 器 API， 我 们 可 以 通过 这 个 API 来 


在 程序 清单 9.4 中 ， 我 们 首 和 匈 从 名 为 textInchannel 的 ee 局 ;s 
然后 进入 一 个 转换 问 ， 将 消 恩 载 何 转换 成 大 写 形式 。 通 过 转换 问 之 后 ， 
消 妃 会 由 出 站 通道 适 配 规 来 进行 处 理 。 由 Spring 
Integration file 模 块 的 Files 类 型 创建 的 。 最 后 ， 通 过 对 getO0 的 调用 返 
构建 的 IntegrationFlow。 简 而 言 之 ， pile 了 与 XML 和 Java 
配置 样 例 相 同 的 集成 流 。 


你 可 能 已 经 发 现 ， 与 Java 配 置 样 例 类 似 ， 我 们 不 需要 显 式 声明 通道 
bean。 我 们 引用 了 textInChannel， 如 果 该 名 字 对 应 的 通道 不 存在 ， 那 么 
Spring Integration 会 目 动 创建 它 。 不 过 ， 我 们 也 可 以 显 式 声明 bean。 


对 于 连接 转换 强 和 出 站 通过 适 配 副 的 通 违 ， 我 们 甚至 没有 通过 名 字 


引用 它 。 如 果 需 要 显 式 配置 通道 ， 那 么 我 们 可 以 在 流 定义 的 时 候 通 过 调 
用 channel0 来 引用 它 的 名 称 : 


QBean 
public IntegrationFlow fileWriterFlow() { 
return IntegrationFlows 
.from(MessageChannels.direct("textIinChannel")) 
.<String, String>transform(t -> t.toUpperCase()) 
.Cchannel(MessageChannels.direct("fileWriterChannel")) 


.handle(Files 
.OUtboundAdapter(new File("/tmp/sia5/files")) 
.fileExistsMode(FileExistsMode.APPEND) 
.appendNewLine(true)) 


:Eet(); 





在 使 用 Spring Integration 的 JavaDSL (与 其 他 的 fluent API 类 似 ) 的 
时 候 ， 我 们 必须 要 巧妙 地 使 用 空格 来 剑 持 可 该 性 。 在 这 里 的 样 例 中 ， 我 
小 心思 中 地 使 用 缩 进 来 你 证 代码 块 的 可 读 性 。 对 于 更 长 、 更 复 灯 的 沈 ， 
我 们 甚至 可 以 考虑 将 流 的 一 部 分 抽取 到 单独 的 方法 或 子 流 中 ， 以 实现 更 
好 的 可 访 性 。 


现在 ， 我 们 已 经 看 到 了 如 何 使 用 3 种 不 同 的 方式 来 定义 一 个 简单 的 
流 。 接 下 来 ， 我 们 回 过 头 来 看 一 下 Spring Integration 的 全 景 。 
9.2 ”Spring Integration 功 能 概 祁 
Spring Integration 涵 兰 了 大 量 的 集成 场景 。 如 果 想 将 所 有 的 内 容 放 
到 一 草 中 ， 驶 像 把 一 头 大 象 帮 到 信封 里 一 样 不 现实 。 在 这 里 ， 我 只 会 回 
你 展示 Spring Integration 这 头 大 象 的 照 睫 ， 而 不 是 对 Spring Integration 进 
行 面 面 俱 到 的 讲解 ， 目 的 就 是 让 你 能 够 了 解 它 是 如 何 运 行 的 。 随 后 ， 我 


们 将 会 再 创建 一 个 集成 流 ， 为 Taco Cloud 应 用 添加 新 的 功能 。 


Ee 
人 


J 


集成 流 古 由 一 个 或 多 个 如 下 介绍 的 组 件 组 成 的 。 在 继续 编写 代 公 之 
我 们 先 看 一 下 这 些 组 件 在 集成 流 中 所 扮演 的 角色 。 


通道 《channel) : 将 消 奶 从 一 个 元 系 传 弟 到 男 一 个 元 和 又。 

过 小 器 (filter) : 基于 未 些 断 言 ， 条 件 化 地 允许 茶 些 消息 通过 流 。 
转换 堪 (transformer) : 改变 消息 的 值 和 /或 将 消息 载 傈 从 一 种 奖 型 
转换 成 男 一 种 类 型 。 

跤 由 如 (router) : 将 消 恩 路 由 全 一 个 或 多 个 通道 ， 通 沿 会 基于 少 
恩 的 头 信 息 进 行路 由 。 

切 分 颖 (splitter〉: 将 传 入 的 消息 切割 成 两 个 或 更 多 的 消息 ， 然 后 
将 每 个 消息 用 送 至 不 同 的 通道 ; 

聚合 硕 (aggregator) : 切 分 左 的 反 同 操作， 将 来 目 不 同 通道 的 多 
个 消 明 合并 成 一 个 消 忌 。 

服务 诉 活 左 (service activator) : 将 消息 传递 给 条 个 Java 方 法 来 进 
行 处 理 ， 并 将 返回 值 发布 到 输出 通道 上 。 

通 媳 适配器 (channel adapter) : 将 通道 连接 到 霖 些 外 部 系统 或 传 
输 方 式 ， 可 以 接受 输入 ， 也 可 以 写 出 到 外 部 系统 。 

网 天 (gateway): 通过 接口 将 数据 传递 到 集成 流 中 。 


在 定义 文件 写 入 集成 流 的 时 候 ， 我 们 已 经 看 到 过 其 中 的 一 些 组 件 
FileWriterGateway 是 一 个 网 关 ， 通 过 它 ， 应 用 可 以 提交 要 与 入 文件 


的 文本 。 我 们 还 定义 了 一 个 转换 磺 ， 将 给 定 的 文本 转换 成 大 写 的 形式 ， 
随后 ， 我 们 定义 一 个 出 站 通道 适 配 硕 ， 筷 执行 将 文本 写 入 文件 的 任务 。 
这 个 流 有 两 个 通道 ，textInChannel 和 fileWriterChannel， 它 们 将 应 用 中 的 
其 他 组 件 连 接 在 了 一 起 。 现 在 ， 我 们 按照 承诺 快速 看 一 下 这 些 集 成 法 组 


Pr 


ME 


9.2.1 少 县 通道 


消息 通道 是 消 上 罕 行 集成 通道 的 一 种 方式 〈 人 参见 图 9.2) 。 它 们 是 
连接 Spring Integration 其 他 组 成 部 分 的 管道 。 





图 9.2 ” 消 明 通道 是 集成 流 中 数据 在 其 他 组 件 之 间 流 动 的 省 过 
Spring Integration 提 供 了 多 种 通道 实现 。 


e。 PublishSubscribeChannel: 发 送 到 PublishSubscribeChannel 的 消息 会 
锐 传 递 到 一 个 或 多 个 消费 者 中 。 如 有 果 有 多 个 消费 者 ， 它 们 都 会 接收 
到 消 忌 。 

。 QueueChannel: 发 送 到 QueueChannel 的 消息 会 存储 到 一 个 队列 中 ， 
会 按照 先进 先 出 (First In First Out，FIFO) 的 方式 被 拉 取 出 来 。 如 
果 有 多 个 消费 者 ， 只 有 其 中 的 一 个 消费 者 会 接收 a 到 消 忆 。 

e。 PriorityChannel: 与 QueueChannel 类 似 ， 但 它 不 是 FIFO 有 的 方式 ， 而 
是 会 基于 消 恩 的 priority 头 信息 个 消费 者 拉 取 出 来 。 

e。 RendezvousChannel: 与 QueueChannel 类 似 ， 但 是 发 送 者 会 一 直 阻 塞 
通道 ， 生 到 消费 者 接收 到 消 上 为 止 ， 实 际 上 会 同步 及 大 者 和 消费 
者 。 

e。 DirectChannel: 与 PublishSubscribeChannel 类 似 ， 但 是 消息 只 会 发 送 
至 一 个 消费 者 ， 它 会 在 与 发 送 者 相同 的 线程 中 调用 消费 者 。 这 种 方 
式 人 允许 事务 路 通道 。 


。 ExecutorChannel: 类 似 于 DirectChannel， 但 是 消息 分 发 是 通过 
TaskExecutor 实 现 的 ， 这 样 会 在 与 发 送 者 独立 的 线程 中 执行 。 这 种 
通道 类 型 不 文 持 事务 路 通道 。 

。 FluxMessageChannel: 反应 式 流 的 发 布 者 消 晨 明 媳 ， 基 于 Reactor 项 
目的 Flux。 (我 们 将 会 在 第 10 章 讨论 反应 式 流 、Reactor 和 Flux。) 


在 Java 配 置 和 Java DSL 中 ， 输 入 通道 都 是 目 动 创 建 的 ， 默 认 使 用 的 
征 DirectChannel。 但 是 ， 如 采 想 要 使 用 不 同 的 通道 实现 ， 允 需 要 将 通道 
声明 为 bean 并 在 集成 流 中 引用 它 。 例 如 ， 要 声明 
PublishSubscribeChannel， 我 们 需要 声明 如 下 的 @Bean 方 法 : 


QBean 
public MessageChannel orderChannel() { 


return new PublishSubscribeChannel(); 





} 


随后 ， 我 们 可 以 在 集成 流 定 义 中 根据 通道 名 称 引 用 它 。 例 如 ， 这 个 
通道 要 被 一 个 服务 激活 右 bean 所 消费 ， 那 么 我 们 可 以 在 
(@ServiceActivator 注 解 的 nputChannel 属 性 中 引用 它 : 


或 者 ， 使 用 Java DSL 配 置 风格 ,我们 可 以 通过 调用 channel0) 来 引用 


QBean 
public IntegrationFlow orderFlow() { 
return IntegrationFlows 


.channel("orderChannel") 


.get(); 





很 重要 的 一 点 需要 注意 ， 如 采 使 用 QueueChannel， 谢 惕 者 必须 配置 
一 个 poller。 例 如 ， 声 明 一 个 QueueChannel bean: 


QBean 
public MessageChannel orderChannel() { 


return new QueueChannel(); 





} 


那么 ， 我 们 需要 确保 消费 者 配置 成 轮 询 访 通道 的 消息 。 如 果 是 服务 
油 活 器 ，@ServiceActivator 注 解 可 能 会 如 下 所 示 : 


@ServiceActivator(inputChannel="orderChannel", 





poller=@Poller (fixedRate="1660")) 


在 本 例 中 ， 服 务 激活 器 每 秒 〈( 或 者 说 每 1000 蜡 秒 )〉 都 会 轮 询 名 为 
orderChannel 的 通道 。 


9.2.2 ”过 滤器 


过 滤器 放置 于 集成 管道 的 中 间 ， 它 能 够 根据 断言 允许 或 拒绝 消息 进 
入 流程 的 下 一 步 〈 见 网 9.3) 。 


可 | 


过 滤器 
图 9.3 ”过 小 器 会 基于 菏 个 断言 允许 或 拒绝 消 居 在 管道 中 进行 处 理 


例如 ， 假 设 消 虫 包含 了 整 型 的 值 ， 它 们 要 通过 名 为 numberChannel 
的 通道 进行 有 布 ， 但 是 我 们 只 想 让 倩 数 进 入 名 为 evenNumberChannel 的 


通道 。 在 这 种 情况 下 ， 我 们 可 以 使 用 @Filter 广 解 定 过 沽 大 


@Filter(inputChannel="numberChannel", 
outputChannel="evenNumberChannel") 


public boolean evenNumberFilter(Integer number) { 
return number % 2 == 0; 


} 





作为 奉 代 方案 ， 如 果 使 用 Java DSL 配 置 风格 来 定义 集成 流 ， 那 么 我 
们 可 以 按照 如 下 的 方式 来 调用 filter(): 


QBean 


public IntegrationFlow evenNumberFlow(AtomicInteger integerSource) { 
return IntegrationFlows 


.<Integer>filter((p) ->p % 2 == 0) 


.get(); 





在 本 例 中 ， 我 们 使 用 lambda 表 达 Pt 寺 小 器。 实际 上 ，filter() 
on 这 意味 看 ， 如 果 我 们 的 过 小 器 过 于 
复杂 ， 不 适合 放 到 一 个 简单 的 lambda 表 达 式 中 ， 那 么 我 们 可 以 实现 
GenericSelector 接 口 作 蔡 代 方案 。 


9.2.3 ”转换 器 


转换 亏 会 对 消息 执行 一 些 操作 ， 一 般 会 形成 不 同 的 消 轧 ， 有 可 能 还 

会 产生 不 同 的 载荷 类 型 〈 见 图 9.4) 。 转 换 过 程 可 能 非常 简单 ， 比 如 执 

行 数字 的 数学 运算 或 者 操作 String 值 。 转 换 也 可 能 会 很 复杂 ， 比 如 根据 
代表 ISBN 的 String 值 查询 并 返回 对 应 图 书 的 详细 信息 。 


口 口 国 口 OO®O 





转换 家 





图 9.4 转换 融会 改变 流 经 集成 流 的 消 奶 


例如 ， 假 设 整 型 信 会 通过 名 为 numberChannel 的 通道 进行 有 发布， 我 
们 希望 将 这 些 数字 转换 成 它们 的 罗马 数字 形式 ， 以 String 类 型 来 表示 。 
在 这 种 情况 下 ， 我 们 可 以 声明 一 个 GenericTransformer 类 型 的 bean 并 为 其 
洪 加 @Transformer 注 艇 ， 如 下 所 示 : 
QBean 


@Transformer(inputChannel="numberChannel", 
outputChannel="romanNumberChannel") 


public GenericTransformer<Integer, String> romanNumTransformer() { 
return RomanNumbers::toRoman; 


} 





@Transformer 注 解 可 以 将 这 个 bean 声 明 为 转换 器 bean， 它 会 从 名 为 
numberChannel 的 通道 接 路 Integer 值 ， 然 后 使 用 静态 方法 toRoman0 进 行 
转换 。 (toRoman0) 是 静态 方法 ， 定 义 在 名 为 RomanNumbers 的 类 中 ， 这 
里 通过 方法 引用 来 使 用 它 。) 转换 后 的 结果 会 肥 布 到 名 为 


romanNumberChannel 的 通道 中 。 


在 Java DSL 配 置 风格 中 ， 调 用 transformO 会 更 加 简单 ， 我 们 只 需 将 
对 toRoman0 的 方法 引用 传递 进来 束 可 以 了 : 





QBean 
public IntegrationFlow transformerFlow() { 
return IntegrationFlows 


.transform(RomanNumbers: :toRoman) 


.get(); 
} 


尽管 在 这 两 个 转换 器 代码 中 我 们 都 使 用 了 方法 引用 ， 但 是 转换 器 也 
可 以 使 用 lambda 表 达 式 来 进行 声明 。 或 者 ， 如 果 转 换 器 足够 复杂 ， 需 要 
使 用 一 个 单独 的 类 ， 那 么 我 们 可 以 将 其 作为 一 个 bean 注 入 流 定 义 中 ， 并 
将 引用 传递 给 transform() 方 法 : 


QBean 
public RomanNumberTransformer romanNumberTransformer() { 
return new RomanNumberTransformer(); 


} 


QBean 
public IntegrationFlow transformerFlow( 


RomanNumberTransformer romanNumberTransformer) { 
return IntegrationFlows 


.transform(romanNumberTransformer) 


.get(); 





在 这 里 ， 我 们 声明 了 RomanNumberTransformer 类 型 的 bean， 它 本 刁 
是 Spring Integration Transformer 或 GenericTransformer 接 口 的 实现 。 这 个 
bean 注 入 到 了 transformerFlow0 方 法 中 ， 并 且 在 定义 集成 流 的 时 候 传递 
给 了 transform() 方 法 。 


9.2.4 路 由 器 


路 由 器 能 够 基于 菏 个 路 由 靳 膏 ， 实 现 集成 法 的 分 文 ， 从 而 将 消 居 友 
达 人 至 不 同 的 通道 上 《上 见 图 9.5) 。 
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图 9.5 路 由 大 会 根据 应 用 于 消息 的 断言 将 消息 定 癌 全 不 同 的 通道 


例如 ， 假 设 我 们 有 一 个 名 为 numberChannel 的 通道 ， 它 会 传输 整 型 
值 。 我 们 枪 要 将 珊 有 代数 的 消息 定 回 到 名 为 evenChannel 的 通道 ， 将 市 
有 奇数 的 消息 定 问 到 名 为 oddChannel 的 通道 。 要 在 集成 流 中 创建 这 样 一 
个 路 由 器 ， 我 们 可 以 声明 一 个 AbstractMessageRouter 类 型 的 bpean， 并 为 
其 深 加 @Router 广 解 : 


QBean 
QRouter(inputChannel="numberChannel") 
public AbstractMessageRouter evenOddRouter() { 
return new AbstractMessageRouter() { 
QOverride 
protected Collection<MessageChannel> 
determineTargetChannels(Message<?> message) { 
Integer number = (Integer) message.getPpayload!(); 
if (number % 2 == 0) { 
return Collections.singleton(evenChannel()); 


} 


return Collections.singleton(oddChannel()); 


| 
} 


QBean 
public MessageChannel evenChannel() { 
return new DirectChannel(); 


} 


QBean 
public MessageChannel oddChannel() { 
return new DirectChannel(); 





} 


这 里 定义 的 AbstractMessageRonuter 接 收 名 为 numberChannel 的 输入 通 
道 的 消息 ， 以 匿名 内 有 轧 的 载 苛 :如 末 是 偶数 ， 融 返回 
名 为 evenChannel 的 通道 〈 在 路 由 堪 bean 之 后 同样 以 bean 的 方 取 进行 了 户 
明 ) ; 售 则 ， 通 道 载 荷 中 的 数字 必然 是 奇数 ， 将 会 返回 名 为 oddChannel 
的 通道 “同样 oni 的 方式 进行 了 声明 ) 。 


在 Java DSL 风 格 中 ， 路 由 此 是 退 过 在 流 定 义 中 调用 routeO 方 法 来 声 
明 的 ， 如 下 所 示 : 
QBean 


public IntegrationFlow numberRoutingFlow(AtomicInteger source) { 
return IntegrationFlows 


.<Integer, String>route(n -> n%2==0 ? "EVEN":"ODD", mapping -> mappi 


.SubFlowMapping("EVEN", sf -> sf 
.<Integer, Integer>transform(n -> n * 10) 
.handle((i,h) -> { ... }) 

) 

.SUbFlowMapping("ODD", sf -> sf 
.transform(RomanNumbers: :toRoman) 
.handle((i,h) -> { ... }) 

) 

) 

.get() ; 





尽管 我 们 依然 可 以 定义 AbstractMessageRouter 并 将 其 传递 到 
route0， 但 是 在 这 个 样 例 中 使 用 了 了 lambda 来 确定 消 县 载 衙 是 偶数 还 是 奇 
数 。 如 果 是 偶数 ， 就 会 返回 值 为 EVEN 的 字符 串 ; 如 果 是 奇数 ， 就 会 返 
回 值 为 ODD 的 字符 串 。 然 后 这 些 值 会 用 来 确定 该 使 用 哪个 子 映射 处 理 消 


自 
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9.2.5 ” 切 分 器 


在 集成 流 中 ， 有 时 候 将 一 个 消 居 切 分 为 多 个 消 恩 独立 处 理 可 能 会 非 
曙 有 用 。 切 分 卓 将 会 负 员 切 分 并 处 理 这 些 消 忌 ， 如 图 9.6 所 示 。 
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图 9.6” 切 分 器 会 将 消息 拆 分 为 两 个 或 更 多 独立 的 消息 ， 它 们 可 以 由 独立 的 子 流 分 别 进 行 处 理 


在 很 多 场景 中 ， 切 分 器 都 非常 有 用 ， 但 是 有 两 种 基本 的 使 用 场景 我 
们 可 以 使 用 切 分 亏 。 


。 省 恩 载 衙 中 包含 了 相同 闫 型 条 目的 一 个 列表 ， 我 们 希望 将 它们 作为 
单独 的 消息 载 衙 来 进行 处 理 。 例 如 ， 靖 轧 中 携 市 了 一 个 商品 列表 ， 
它们 可 以 切 分 为 多 个 消 轧 ， 每 个 请 轧 的 载 千 分 别 对 应 一 件 商 品 。 

。 诊 居 载 傈 所 携 市 的 信息 尽 定 有 所 关联， 但 是 可 以 拆 分 为 两 个 或 更 多 
不 同类 型 的 消 明 。 例 如 ， 一 个 购 丑 订 蛙 可 能 会 包含 投 好 信息 、 账 持 
以 及 商品 项 的 信息 。 投 递 细节 可 以 通过 未 个 子 流 来 处 理 ， 账 单 由 万 
一 个 子 流 来 处 理 ， 而 商品 项 由 其 他 的 子 流 来 处 理 。 在 这 种 情况 下 ， 
切 分 右 后 面 通 第 会 紧 跟 看 一 个 路 由 上 帝 ， 它 根据 消 恩 的 载 傈 类 型 进行 
路 由 ， 确 保 数据 都 由 正确 的 子 流 来 进行 处 理 。 


在 我 们 将 消 明 载 傈 切 分 为 两 个 或 更 多 不 同类 型 的 消 忌 时 ， 通 第 定义 
一 个 POJO 束 足够 了 ， 它 提取 传 入 消 明 人 不同 的 组 成 部 分 ， 并 以 元 系 集合 
的 形式 返回 。 


例如 ， 假 设 我 们 想 要 将 市 有 购买 订单 的 消 奶 切 分 为 两 个 消 居 :其 中 
一 个 携 宫 账单 信息 ， 男 一 个 携 和 之 了 两 品 项 的 信息 。 如 下 的 OrderSplitter 束 
可 以 完成 该 任务 : 


public class OrderSplitter 1{ 
public Collection<Object> splitOrderIntopParts(PurchaseOrder po) { 
ArrayList<Object> parts = new ArrayList<>(); 
parts.add(po.getBillingInfo( ) ) ; 


parts.add(po.getLineItems( ) ) ; 
return parts,; 


} 
} 





接 下 来 ， 我 们 声明 一 个 OrderSplitter bean， 并 通过 @Splitter 注 解 将 
其 作为 集成 流 的 一 部 分 : 
QBean 


@splitter(inputChannel="poChannel", 
outputChannel="splitOrderChannel") 


public OrderSplitter orderSplitter() { 
return new OrderSplitter(); 





} 


在 这 里 ， 购 买 订单 会 到 达 Wp 道 ， 它 们 会 被 
OrderSplitter 切 分 。 然 后 ， 所 返回 集合 中 的 每 个 条 目 都 会 作为 集成 流 中 
独立 的 消 轧 ， 它 们 会 发 布 aeons 道上 。 此 时 ， 我 
们 可 以 在 流 中 声明 一 个 PayloadTypeRouter， 将 账单 信息 和 商品 项 分 别 路 
由 全 它们 目 己 的 子 流 上 : 





QBean 
@QRouter(inputChannel="splitOrderChannel") 
public MessageRouter splitOrderRouter() { 
PayloadTypeRouter router = new PayloadTypeRouter( ) ; 
router.setChannelMapping( 
BillingInfo.class.getName(), "billingInfoChannel"); 


router.setChannelMapping( 
List.class.getName(), "lineItemsChannel"); 
return Fouter ; 


} 





顾名思义 ，PayloadTypeRouter 会 根据 消 明 的 载 何 将 它们 路 由 至 不 同 
的 通道 。 按 照 这 里 的 配置 ， 载 傈 为 BillingInfo 类 型 的 消 居 将 会 外 路 由 至 
名 为 billingInfoChannel 的 通道 ， 供 后 续 进 行 处 理 。 对 于 了 商品 项 来 说 ， 它 
们 会 放 到 一 个 javautil.List 集 合 中 ， 因 此 ， 我 们 将 List 关 型 的 载 傈 映射 到 
名 为 lineItemsChannel 的 通 站 中 。 


按照 目前 的 状况 ， 流 将 会 饭 切 分 成 两 个 子 法: 一 个 BillingInfo 对 象 
的 流 ， 男 外 一 个 则 是 List<LineItem> 的 流 。 如 末 我 们 想 要 进一步 进行 拆 
分 ， 比 如 人 不想 处 理 LineItems 的 列表 ， 而 是 想 要 分 别处 理 每 个 LineItem， 
又 该 夭 么 办 呢 ? 要 将 商品 列表 拆 分 为 多 个 消 轧 ， 其 中 每 个 消息 包含 一 71 
条 目 ， 我 们 只 需要 编写 一 个 方法 《而 不 是 一 个 bean) 即 可 。 这 个 方 读 市 
有 @Splitter 注 解 并 且 要 返回 LineItem 的 集合 ， 如 下 上 所 示 : 


@Splitter(inputChannel="lineItemsChannel", outputChannel="lineItemChannel" 
) 


public List<LineItem> lineItemSplitter(List<LineItem> lineItems) { 
return lineItems; 


} 





当 禹 有 List<Lineltem> 载 全 的 消 恩 抵达 名 为 lineltemsChannel 的 通道 
时 ， 消 晨 会 进入 lineItemSplitter()。 按 照 切 分 器 的 规则 ， 这 个 方法 必须 要 
返回 切 分 后 条 目的 集合 。 在 本 例 中 ， 我 们 已 经 有 了 Lineltem 的 集合 ， 所 
以 我 们 直接 人 返回 这 个 集合 束 可 以 了 。 这 样 做 的 结果 束 是 ， 集 合 中 的 每 个 
LineItem 都 将 会 肥 布 到 一 个 消 息 中 ， 这 些 消息 会 航 及 送 到 名 为 


lineItemChannel 的 通道 中 。 


如 末 想 要 使 用 Java DSL 声 明 相同 的 splitter/router 配 置 ， 那 么 我 们 可 
以 通过 调用 split0 和 route0 来 实现 : 


return IntegrationFlows 


.Split(orderSplitter()) 
.<Object, String> Poute( 
p -> 1 
if (p.getClass().isAssignableFrom(BillingInfo.class)) { 
return “BILLING INFO"; 
} else 1{ 
return “LINE ITEMS",; 
} 
}, mapping -> mapping 
.SUbFlowMapping("BILLING INFO", sf -> sf 
.<BillingInfo> handle((billingInfo, h) -> { 


})) 
.SUubFlowMapping("LINE ITEMS", sf -> sf 


.Split() 
.<LineItem> handle((lineItem, h) -> { 





DSL 所 组 成 的 流 定义 相当 简洁 ， 但 是 可 能 会 有 点 难以 理解 。 它 使 用 
与 Java 配 置 样 例 相 同 的 OrderSplitter 来 切 分 订单 。 在 订单 切 分 之 后 ， 它 根 
据 类 型 将 其 路 由 至 两 个 独立 的 子 流 。 

9.2.6 ”服务 油 活 此 


服务 油 活 此 接 收 来 目 输 入 退 追 的 消 恩 并 将 这 些 消 恩 友 友 全 一 11 


MessageHandler 的 实现 ， 如 图 9.7 所 示 。 
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图 9.7 在 接收 到 消 恩 上 时， 服务 激活 右 会 通过 MessageHandler 调 用 某 个 服务 


Spring Integration 提 供 了 多 个 开 箱 即 用 的 
MessageHandler (PayloadTypeRouter 其 至 就 是 MessageHandler 的 一 个 实 
现 ) ， 但 是 我 们 通 沿 会 需要 提供 一 些 自 定 义 的 实现 作为 服务 激活 问 。 作 
为 样 例 ， 如 下 的 代码 展现 了 如 何 声 明 MessageHandler bean 并 将 其 配置 为 
服务 激活 右 : 


QBean 
QServiceActivator(inputChannel="someChannel") 
public MessageHandler sysoutHandler() { 


return message ->{ 

System.out.println("Message payload: ”+ message.getPay1oad() ) ; 
】 
} 





这 个 bean 使 用 了 @ServiceActivator 注 解 ， 表 明 它 会 作为 一 个 服务 激 
活 堪 处 理 来 目 someChannel 通 道 的 消息 。 对 于 MessageHandler 本 喘 来 讲 ， 
它 是 通过 一 个 lambda 表 达 式 实现 的 。 这 是 一 个 简单 的 MessageHandler， 
当 得 到 消 恩 之 后 ， 它 会 将 消 明 的 载 何 打印 至 标准 输出 流 。 


为 外 ， 我 们 还 可 以 声明 一 个 服务 沿 活 融 ， 让 它 在 返回 新 载 何 之 二 处 
理 输入 消 胀 中 的 数据 。 在 这 种 情况 下 ，bean 应 该 是 一 个 


GenericHandler， 而 不 是 MessageHandler: 


QBean 

@ServiceActivator(inputChannel="orderChannel",， 
outputChannel="completeOrder") 

public GenericHandler<Order> orderHandler( 


OrderRepository orderRepo) { 
return (payload, headers) -> { 
return orderRepo.save(payload); 
}; 
} 





在 本 例 中 ， 服 务 籼 活 占 是 一 个 GenericHandler， 会 接收 载 傈 为 Order 
类 型 的 消息 。 当 订单 抵达 时 ， 我 们 会 通过 一 个 repository 将 它 保存 起 来 ， 
并 返回 保存 之 后 的 Order， 这 个 Order 随 后 被 及 达 至 名 为 completeChannel 
的 输出 通道 。 


你 可 能 已 经 注意 到 了 ，GenericHandler 个 仪 能 够 得 到 载 人 入 ， 还 能 得 
到 消 轧 头 《〈《 虽 然 我 们 这 个 样 例 根本 没有 用 到 这 些 头 信息 ) 。 我 们 还 可 以 
在 Java DSL 配 置 风 格 中 使 用 服务 激活 规 ， 此 时 ， 只 需要 将 
MessageHandler 或 GenericHandler 传 递 到 流 定 义 的 handle0 方 法 中 即 可 : 


public IntegrationFlow someFlow() { 
return IntegrationFlows 


.handle(msg -> { 


System.out.println("Message payload: ”+ msg.getPpayload()); 





在 本 例 中 ，MessageHandler 会 得 到 一 个 lambda 表 达 式 ， 但 是 我 们 也 
可 以 为 其 提供 一 个 方法 引用 ， 甚 至 是 实现 了 MessageHandler 接 口 的 类 实 
例 。 如 果 我 们 为 其 所 供 lambda 表 达 式 或 方法 引用 ， 丈 需要 记 住 它们 均 接 


类 似 的 ， 如 果 服 务 激 活 峰 不 想 成 为 流 的 终点 ， 那 么 handleO 还 可 以 
接受 GenericHandler。 如 果 要 将 前 面 提 到 的 订单 保存 服务 激活 髓 谎 加 进 
来 ， 我 们 可 以 按照 如 下 的 形式 使 用 Java DSL 配 置 流 : 


public IntegrationFlow orderFlow(OrderRepository orderRepo) { 
return IntegrationFlows 


.<Order>handle((payload, headers) -> { 


return orderRepo.save(pay1oad ) ; 


}) 


.get(); 





在 使 用 GenericHandler 的 时 候 ，lambda 表 达 式 或 方法 引用 会 接受 消 
恩人 负载 和 头 信 息 作为 参数 。 如 果 你 选择 使 用 GenericHandler 作 为 流 的 终 


9.2.7 ”网关 


通过 网 关 ， 应 用 可 以 提交 数据 到 集成 流 中 ， 并 且 能 够 可 选 地 接收 流 
的 结果 作为 响应 。 网 关 会 声明 为 接口 ， 借 助 Spring Integration 的 实现 ， 
应 用 可 以 调用 它 来 发 送 消息 到 集成 流 中 ( 见 图 9.8)。 





图 9.8 ”服务 网 关 是 接口 


我 们 已 经 见 过 了 消息 网 天 的 样 例 ， 也 焉 是 FileWriterGateway。 
FileWriterGateway 是 一 个 单 同 的 网 天 ， 它 有 一 个 接受 String 类 型 的 方法 ， 
该 方法 会 将 文本 写 入 到 文件 中 ， 返 回 void。 编 写 双 同 的 网 关 同 样 简 单 。 
在 编写 网 天 接口 的 时 候 ， 只 需 确 保 方 法 要 返回 茶 个 什 ， 以 便于 推送 到 集 
成 法 中 。 


作为 样 例 ， 假 设 有 个 网 关 ， 它 面 对 的 是 一 个 简单 的 集成 流 ， 这 个 流 
会 接受 一 个 String 并 将 给 定 的 String 转 换 成 全 大 写 的 形式 。 这 个 网 关 接 口 
大 致 如 下 所 示 : 


package com.example.demo; 

Import org.springframework.integration.annotation.MessagingGateway; 
Import org.springframework.stereotype.Component,; 

QComponent 


@QMessagingGateway (defaultRequestChannel="inChannel",， 
defaultReplyChannel="outChannel") 
public interface UpperCaseGateway { 
String uppercase(String in); 





} 


最 让 人 开心 的 是 ， 这 个 接口 不 需要 实现 。Spring Integration 会 目 动 
在 运行 时 提供 一 个 实现 ， 它 会 通过 特定 的 通道 发 送 和 接收 消 居 。 


当 uppercase(0) 被 调用 的 时 候 ， 给 定 的 String 会 友 布 到 集成 流 中 ， 进 入 
名 为 inpChannel 的 通道 。 不 管 流 是 如 何 定 义 的 或 者 它 都 干 了 些 什 么 ， 当 数 
据 进 入 名 为 outChannel 的 通道 时 ， 它 将 会 从 uppercase() 方 法 返回 。 


对 于 我 们 这 个 转换 成 大 写 格式 的 集成 流 来 说 ， 它 是 一 个 非常 简单 的 
流 ， 只 需要 一 个 将 String 转 换 成 大 写 格式 的 步 又 就 可 以 。 它 可 以 通过 
JavaDSL 配 置 声 明 如 下 : 


QBean 
public IntegrationFlow uppercaseFlow() { 
return IntegrationFlows 
.from("inChannel") 


.<String, String> transform(s -> s.toUpperCase() ) 
.channel("outChannel") 


.get() ; 





按照 定义 ， 这 个 流 会 从 进入 inChannel 通 道 的 数据 开始 。 消 恩 载 奏 会 
由 转换 颖 进行 处 理 ， 也 就 是 执行 大 与 操作 (通过 lambda 表 达 式 来 定 
义 )。 结 琳 形 成 的 消 奶 会 修 发 运 到 名 为 outChannel 的 通道 ， 也 束 是 我 们 
企 UpperCaseGateway 中 声明 的 答复 角道 。 


9.2.8 通 直 适 配 瑚 
通道 适配器 代表 了 集成 流 的 入 口 和 出 口 。 数 据 通 过 入 站 通道 适配器 


(inbound channel adapter) 进入 一 个 集成 流 ， 通 过 出 站 通道 适 配 右 离开 
一 个 集成 流 ， 如 图 9.9 所 示 。 


i Dt ) 
下 
入 站 通道 适配器 人 出 站 通道 适配器 


图 9.9 ”通道 适 配 需 是 集成 流 的 入 口 和 出 口 
人 入 站 通道 适 配 需 可 以 有 很 多 种 形 


式 。 例 如 ， 我 们 可 以 声明 一 个 入 站 通道 适配器 ， 将 来 目 AtomicInteger 不 
源 违 增 的 数字 引入 到 流 中 。 如 果 使 用 Java 配 置 ， 如 下 所 示 : 


QBean 
@InboundChannelAdapter( 

poller=@Poller(fixedRate="166060"), channel="numberChannel") 
public MessageSource<Integer> numberSource(AtomicInteger source) { 


return () -> { 
return new GenericMessage<>(source.getAndIncrement()); 
}; 
} 





这 个 @Bean 方 法 通过 @InboundChannelAdapter 注 解 声 明了 一 个 入 站 
正 配 硕 ， 根 据 注 入 的 AtomicInteger 每 WE (也 就 是 1000 毫 秒 ) 就 
提交 一 个 数字 给 名 为 numberChannel 的 通 


在 使 用 Java 配 置 时 ， 我 们 可 以 通过 @InboundChannelAdapter 注 解 声 
明 入 站 通道 适配器 ， 而 在 使 用 Java DSL 定 义 集 成 流 的 时 候 ， 我 们 需要 使 
7 如 下 的 注定 义 程序 清 蛙 展现 了 类 似 的 入 
站 通道 适 配 左 ， 它 是 使 用 Java DSL 定 义 的 : 





QBean 
public IntegrationFlow someFlow(AtomicInteger integerSource) { 
return IntegrationFlows 
.from(integerSource, "getAndIncrement",， 
Cc -> c.poller(Pollers.fixedRate(16060))) 


get(); 
} 


nm 
假设 ， 我 们 需要 一 个 入 站 通道 适配器 ， 它 会 监控 一 个 特定 的 目录 并 将 写 
入 该 目录 的 文件 以 消 明 的 形式 提交 到 file-channel 通 道中 。 如 下 的 Java 配 
置 使 用 来 日 Spring Integration 的 file 绒 点 模块 实现 该 功能 : 
QBean 


@InboundChannelAdapter(channel="file-channel", 
poller=@Poller(fixedDelay="106080 


")) 


public MessageSource<File> fileReadingMessageSource() { 


FileReadingMessageSource sourceReader = new FileReadingMessageSource( ) ; 
sourceReader .setDirectory(new File(INPUT DIR),); 

sourceReader .setFilter(new SimplepatternFilelListFilter(FILE PATTERN)); 
return SourceReader ; 





} 


如 果 使 用 Java DSL 编 写 同 等 功 和 ttt pmb 
使 用 Files 类 的 inboundAdapter()。 出 站 通道 适 配 絮 是 集成 流 的 终点 ， 会 将 
最 终 的 消息 传递 给 应 用 或 其 他 外 部 系统 
QBean 


public IntegrationFlow fileReaderFlow() { 
return IntegrationFlows 


.from(Files.inboundAdapter(new File(INPUT DIR)) 
.patternFilter(FILE PATTERN)) 


.get() ; 





我 们 通 沿 会 将 服务 激活 器 实现 为 消 居 人 处理 器， 让 它 作 为 出 站 通道 适 
配 右 ， 在 数据 需要 传递 给 应 用 本 刁 的 时 候 更 是 如 些 。 我 们 已 经 讨论 过 服 
务 激活 磺 ， 所 以 没有 必要 重复 讨论 了 了。 


但 是 ， 需 要 注意 ，Spring Integration 闪 点 模块 为 多 个 通用 场景 近 供 
了 消息 处 理 器 。 在 程序 清单 9.3 中 ， 我 们 已 经 见 到 过 一 个 这 种 出 站 通道 
适 配 鼎 的 样 例 ， 即 FileWriting MessageHandler。 捉 到 Spring Integration 病 
点 模块 ， 我 们 看 一 下 都 有 哪些 直接 可 用 的 集成 端点 模块 。 


9.2.9 ”端点 模块 


Spring Integration 允 许 我 们 创建 目 己 的 通道 适配器 ， 这 一 点 非 音 
好 ， 但 是 更 棒 的 是 Spring Integration 提 供 了 二 十 多 个 包含 通道 适 配 需 
《同时 包括 入 站 和 出 站 的 适 配 问 ) 的 问 点 模块 〈 见 表 9.1) ， 用 于 和 各 
种 常见 的 外 部 系统 实现 集成 。 


表 9.1 ”Spring Integration 提 供 的 二 十 多 个 端点 模块 


依赖 的 artifact ID (Group ID: org.springframework.integration ) 


AMOQP spring-integration-amqp 


RSS 和 Atom spring-integration-feed 
文件 系统 spring-integration-file 
FTP/FTPS spring-integration-ftp 





GemFElre 


Spring-integration-gemfire 


Spring-integration-http 


Spring-integration-jdbc 


Spring-integration-j]pa 


Spring-integration-]ms 


Spring-integration-maijl 


Spring-integration-mongodb 


Spring-integration-mdtt 


Spring-integration-redis 


Spring-integration-Trml 


Spring-integration-sftp 


spring-integration-stomp 


spring-integration-stream 





Syslog spring-integration-syslog 


WebSocket spring-integration-websocket 
XMPP spring-integration-xmpp 
spring-integration-zookeeper 





从 表 9.1 我 们 可 以 清楚 地 看 到 ，Spring Integration 提 供 了 用 途 广 泛 的 
一 组 组 件 ， 它 们 能 够 满足 非 第 多 的 集成 需求 。 大 多 数 应 用 程序 所 使 用 的 
只 是 Spring Integration 所 提供 功能 的 九 牛 一 毛 。 需 要 的 话 ， 我 们 最 好 还 
是 要 知道 Spring Integration 己 经 提供 了 相关 的 功能 。 


男 外 ， 我 们 不 可 能 在 一 半 的 遍 幅 中 介绍 表 9.1 中 的 所 有 通道 适 配 
研 。 我 们 已 经 看 到 了 如 何 使 用 文件 系统 模块 写 入 文件 的 样 例 ， 随 后 将 会 
看 到 如 何 使 用 Email 模块 来 读 取 Email。 


对 于 每 个 端点 模块 的 通道 适配器 ， 我 们 可 以 在 Java 配 置 中 将 其 声明 
为 bean， 也 可 以 在 JavaDSL 配 置 中 通过 况 态 方法 的 方式 引用 。 我 建议 你 
探索 一 下 目 己 感 兴 趣 的 其 他 端点 模块 。 你 会 发 现 它们 在 使 用 方式 上 十 非 
各 一 致 的 。 现 在 ， 我 们 关注 一 下 Email 端点 模块 ， 看 一 下 如 何 将 它 用 到 
Taco Cloud 应 用 中 。 


9.3 创建 Email 集成 流 


我 们 决定 Taco Cloud 应 该 允许 客户 通过 Email 提 交 taco 设 计 和 创建 订 
里 。 我 们 有 发 放 传 单 并 在 报纸 上 刊登 外 卖 广告 ， 邀 请 每 个 人 通过 Email 肥 
达 taco 订 蛙 。 这 非 第 成 功 ! 但 是 ， 令 人 遗憾 的 是 ， 它 过 于 成 功 了 。 有 有 太 
多 的 Email 涌 了 进来 ， 我 们 不 得 不 申请 临时 帮助 ， 让 别人 赔 读 所 有 的 
Email 并 将 订单 提交 到 订 半 系统 中 。 


在 本 方 中 ， 我 们 将 会 实现 一 个 集成 流 ， 轮 询 Taco Cloud 的 taco 订 单 
Email 的 收 件 箱 、 解 析 Email 中 的 订单 细节 并 将 订单 提交 给 Taco Cloud 来 
进行 处 理 。 稍 而 言 之 ， 在 我 们 所 创建 的 集成 流 中 ， 入 站 通道 适 配 右 将 会 
使 用 Email 端点 模块 摄取 Taco Cloud 收 件 箱 中 的 Email 到 集成 流 中 。 


集成 流 的 下 一 步 会 将 Email 解析 为 订单 对 象 ， 这 些 订 单 对 象 会 裤 传 
违 给 男 一 个 处 理 费 ， 从 而 将 订单 所 区 全 Taco Cloud 的 REST API 中 ， 在 这 
里 我 们 会 像 其 他 订单 那样 处 理 它 们 。 首 先 ， 我 们 定义 一 个 简单 的 配置 属 
性 类 ， 它 会 捕获 处 理 Taco Cloud Email 的 特定 信息 : 





@Data 
@ConfigurationProperties(prefix="tacocloud.email") 


QComponent 
public class EmailProperties { 


private String Username ; 
private String password; 
private String host; 

private String mailbox; 
private long pollRate = 30600 ; 


public String getImapUrl() { 
return String.format("imaps://%s:%sQ@%s/%s", 
this.username, this.password, this.host, this.mailbox); 





我 们 可 以 看 到 ，EmailProperties 会 捕获 生成 IMAP URL 的 属性 。 这 个 
流 会 使 用 这 个 URL 连 接 Taco Cloud Email 服 务 如 并 轮 询 Email。 在 捕获 的 
属性 中 包括 Email 用 户 的 用 户 名 和 密码 以 及 IMAP 服 务 器 的 主机 、 要 轮 询 
的 邮箱 以 及 邮箱 轮 询 的 频 京 (默认 为 30 秒 ) 。 


EmailProperties 在 类 级 别 使 用 了 @ConfigurationProperties 注 解 ， 并 将 
prefix 属 性 设置 为 tacocloud.email。 这 意味 看 ， 我 们 可 以 在 application.yml 
文件 中 按照 下 述 方式 配置 消费 Email 的 详细 信息 : 


tacocloud: 
email: 
host: imap.tacocloud.com 


mailbox: INBOX 
Username: taco-in-flow 
password: 1LOov3T4c6s 
poll-rate: 16666 





现在 ， 我 们 使 用 EmailProperties 来 配置 集成 流 。 我 们 想 要 创建 的 流 
大 致 如 图 9.10 所 示 。 





有 一 


Email (IMAP) 邮件 到 订单 的 转换 需 
入 站 通道 适 配 需 适 配 船 


图 9.10 ”通过 Email 接受 taco 订 单 的 集成 流 
我 们 有 两 种 方案 来 定义 这 个 流 。 


。 在 Taco Cloud 应 用 中 进行 定义 : 在 流 的 结束 点 ， 服 务 油 活 器 要 调用 
a 

。 在 单独 的 应 用 中 进行 : 在 流 的 结束 点 ， 服 务 油 活 占 要 发 达 
POST 请 求 到 Taco Ca API 以 提交 taco 订 单 。 


不 官 选 择 哪 种 方式 ， 除 了 服务 油 活 强 的 实现 方式 之 外 ， 对 流 的 本 号 
影 号 并 不 大 。 但 是 ， 因 为 我 们 需要 一 些 表 示 taco、 订 单 和 配料 的 类 型 ， 
它们 与 Taco Cloud 主 应 用 可 能 会 略微 有 所 差 卉 ， 所 以 我 们 会 在 一 个 单独 
的 应 用 中 定义 集成 演 ， 避 免 与 已 有 的 领域 关 型 相 混 消 。 


我 们 还 可 以 选择 使 用 XML 配置 、Java 配 置 或 者 Java DSL 来 定义 流 。 
我 更 喜欢 DSL 的 优雅 ， 所 以 在 这 里 将 会 使 用 这 种 方案 。 如 果 你 想 要 一 些 
籁 外 的 挑战 ， 也 可 以 选择 其 他 配置 风格 编写 流 的 定义 。 现 在 ， 我 们 看 一 
下 taco Email 订 单 流 的 Java DSL 配 置 ， 如 程序 清单 9.5 所 示 。 


程序 清单 9.5 ”定义 接收 Email 并 将 其 提交 为 订单 的 集成 沉 





package tacos.email; 

Import org.springframework.context.annotation.Bean; 

Import org.springframework.context.annotation.Configuration; 
Import org.springframework.integration.dsl.IntegrationFlow; 
import org.springframework.integration.dsl.IntegrationFlows; 
import org.springframework.integration.dsl.Pollers; 


@Configuration 
public class TacoOrderEmailIintegrationConfig 1 


QBean 

public IntegrationFlow tacoOrderEmailFlow( 
EmailProperties emailpProps, 
EmailToOrderTransformer emailToOrderTransformer., 
OrderSubmitMessageHandler orderSubmitHandler) { 


return IntegrationFlows 
.from(Mail.imapInboundAdapter(emailProps.getImapUr1l()), 
e -> e.poller( 
Pollers.fixedDelay(emailProps.getPollRate( )))) 
.transform(emailToOrderTransformer) 
.handle(orderSubmitHandler) 
.get(); 


根据 tacoOrderEmailFlow0 方 法 的 定义 ，taco Email 订 单 流 由 3 个 不 同 
的 组 件 组 成 。 


。 MAP Email 入 站 通关 适 配 秦 : 使 用 IMP URL 创 建 ， 而 URL 是 根据 
EmailProperties 的 getImapUT(0 方 法 创建 的 ， 并 且 会 根据 
EmailProperties 中 设置 的 pollRate 属 性 进行 轮 询 。 传 入 的 Email 会 传 
递 给 一 个 通道 ， 然 后 连接 到 转换 天 

。 将 Email 转换 成 订单 对 象 的 转换 器 : 转换 颖 是 通过 
EmailToOrderTransformer 实 现 的 ， 它 会 注入 tacoOrderEmailFlow0) 方 
法 中 。 转 换 所 形成 的 订单 会 通过 为 外 一 个 通道 传递 给 最 后 一 个 组 
件 。 

F 理 器 (作为 出 站 通道 适配器 ，: 处 理 器 接受 订单 对 象 并 将 其 提交 
全 Taco Cloud 的 REST APIT。 


我 们 只 有 将 Email 痛 点 模 其 作为 依 顿 项 谎 加 到 项 目 构 建文 件 中 ， 才 


能 调用 Mail.imap InboundAdapter()。Maven 依 赖 如 下 所 示 : 


<dependency> 
<grouplId>org.springframework.integration</groupId> 


<artifactId>spring-integration-file</artifactId> 
</dependency> 





EmailToOrderTransformer 是 Spring Integration Transformer 接 口 的 实 


现 ， 扩 展 了 AbstractMailMessageTransformer 〈 如 程序 清单 9.6 所 示 ) 。 
程序 清单 9.6 使 用 集成 转换 右 将 传 入 的 Email 转 换 为 taco 订 单 


QComponent 
public class EmailToOrderTransformer 
extends AbstractMailMessageTransformer<Order> 1{ 


QOverride 
protected AbstractIintegrationMessageBuilder<Order> 
doTransform(Message mailMessage) throws Exception { 


Order tacoOrder = processPayload(mailMessage); 
return MessageBuilder.withpayload(tacoOrder); 


} 





AbstractMailMessageTransformer 是 一 个 很 便利 的 其 类 ， 适 用 于 和 载 何 
为 Email 的 消息 。 它 会 抽取 传 入 消息 Email 的 信息 ， 并 将 它 放 到 一 个 
Message 对 象 中 ， 传 递 给 doTransform( 方 法 。 在 doTransform() 方 法 中 ， 
我 们 将 Message 对 象 传递 给 一 个 名 为 processPayload(O0 的 Private 方法， 将 
Email 解析 为 Order 对 象 。 这 个 Order 对 象 套 管 和 主 Taco Cloud 应 用 中 的 
Order 对 象 有 些 相 似 ， 但 是 并 不 完全 相同 ， 这 里 更 加 简单 一 些 : 


package tacos.email; 
import JjJava.util.ArrayList; 


import JjJava.util.List,; 
import lombok.Data; 


@Data 
public class Order { 
private final String email; 
private List<Taco> tacos = new ArrayList<>(); 


public void addTaco(Taco taco) { 
this.tacos.add(taco); 
} 
} 





这 个 Order 类 不 包含 客户 完整 的 投递 信息 和 账单 信息 ， 而 是 只 携带 


了 客户 的 Email 地 址 〈 通 过 传 入 的 Email 获取 的 ) 。 


将 Email 解析 成 订单 是 一 项 非常 重要 的 任务 。 实 际 上 ， 即 便 最 简单 
的 实现 也 需要 几 十 行 代码 。 这 些 代 人 码 对 于 进一步 讨论 Spring Integration 
和 如 何 实现 转 换 带 并 没有 任何 助 蔓 。 所 以 ， 为 了 克 省 空间 ， 我 在 这 里 省 
略 了 processPayload0) 方 法 的 细节 。 


EmailToOrderTransformer 做 的 最 后 一 件 事 情 束 是 返回 一 ?1 
MessageBuilder， 让 消 恩 的 载 何 中 包含 Order 对 象 。MessageBuilder 所 生 
成 的 消 明 会 发 这 全 集成 法 的 最 后 一 个 组 件 : 将 订单 提交 全 Taco Cloud 
API 的 消息 处 理 需 。OrderSubmitMessageHandler 实 现 了 Spring Integration 
HGenericHandler， 它 会 处 理 市 有 Order 载 傈 的 消 朋 ， 如 程序 消 蛙 9.7 所 


和 修 。 


程序 清单 9.7 通过 消息 处 理 需 将 订单 提交 至 Taco Cloud API 





package tacos.email; 

Import java.util.Map; 

import org.springframework.integration.handler.GenericHandler; 
import org.springframework.stereotype.Component; 


import org.springframework.web.client.RestTemplate,; 


QComponent 
public class OrderSubmitMessageHandler 
ijmplements GenericHandler<Order> { 
private RestTemplate rest; 
private ApiProperties apiProps; 


public OrderSubmitMessageHandler( 
ApiProperties apiProps, RestTemplate rest) { 
this.apiProps = apiProps; 
this.rest = rest; 


} 


QOverride 

public Object handle(Order order, Map<String, Object> headers) { 
rest.postForObject(apiProps.getUrl(), order, String.class); 
return null; 


} 
} 


为 了 满足 GenericHandler 接 口 的 要 求 ，OrderSubmitMessageHandler 
重 写 了 handle0 方 法 ， 这 个 方法 接收 传 入 的 Order 对 象 ， 并 使 用 注入 的 
RestTemplate 利 用 POST 请 求 将 Order 提 交 至 ApiProperties 对 象 指定 的 
URL。 最 后 ，handle0) 方 法 返回 null， 表 明 这 个 处 理 器 是 流 的 终点 。 


这 里 使 用 ApiProperties 避 人 饮 在 postForObject() 时 便 编 码 URL。 它 是 一 
个 配置 属性 类 ， 如 下 所 示 : 
@Data 


@ConfigurationPproperties(prefix="tacocloud.api") 
QComponent 


public class ApiProperties { 
private String url; 





} 


在 application.yml 中 ，Taco Cloud API 的 URL 可 能 会 配置 如 下 : 


tacocloud: | 


api: 
url: http://api.tacocloud.com 


为 了 让 这 个 应 用 能 够 使 用 RestTemplate， 并 自动 注入 
OrderSubmitMessageHandler 中 ， 我 们 需要 在 项 目的 构建 文件 中 这 加 
Spring Boot web starter 依 赖 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-web</artifactId> 
</dependency> 





这 不 仅 会 将 RestTemplate 添 加 到 类 路 径 中 ， 还 会 触 肥 Spring MVC 的 
自动 配置 功能 。 作 为 独立 的 Spring Integration 流 ， 这 个 应 用 并 不 需要 
Spring MVC， 更 不 需要 目 动 配置 所 提供 的 验 入 式 Tomcat。 上 所以， 我 们 
可 以 在 application.yml 中 通过 如 下 的 配置 条 目 葵 用 Spring MVC 的 目 动 配 
前 : 

spring: 
ey none 

spring.main.web-application-type 属 性 可 以 设置 为 servlet、reactive 或 
none。 当 Spring MVC 位 于 类 路 人 径 之 中 时 ， 目 动 配置 功能 会 将 其 设置 为 
servlet。 我 们 在 这 里 将 其 重 写 为 none， 所 以 Spring MVC 和 Tomcat 将 不 会 
进行 目 动 配置 (我 们 将 会 在 第 11 章 介绍 反应 式 Web 应 用 是 什么 样子 
的 ) 。 


9.4 ”小结 


。 借助 Spring integration 能 够 定义 流 ， 在 进入 和 离开 应 用 的 时 候 可 以 
对 数据 进行 处 理 。 

集成 流 可 以 使 用 XML、Java 或 简洁 的 Java DSL 配 置 风格 来 进行 定 
义 。 

。 消息 网 关 和 通道 适 配 融会 作为 集成 流 的 入 口 和 出 口 。 

在 流动 的 过 程 中 ， 消 息 可 以 进行 转换 、 切 分 、 聚 合 、 路 由 ， 也 可 以 
由 服务 激活 峰 对 其 进行 处 理 。 

。 消 县 通道 连接 集成 流 中 的 各 个 组 件 。 


第 3 部 分 反应 式 Spring 


在 第 3 部 分 ， 我 们 将 探索 Spring 对 反应 式 编程 提供 的 全 新 文 持 。 第 
10 半 讨论 使 用 Reactor 项 目 进 行 有 反应 式 编 程 的 基础 知识 。Reactor 项 目 古 
支撑 Spring 5 和 性 的 反应 式 编 程 库 。 然 后 ， 我 们 将 会 介绍 
Reactor 中 一 些 第 用 的 反应 式 操 作 。 在 第 11 半 中 ， 我 们 会 午 新 探讨 REST 
API 的 开发 ， 介 绍 全 新 的 Web 框 架 Spring WebFlex。 访 框架 借用 了 很 多 
Spring MVC 的 理念 ， 为 Web 开 发 提供 了 新 的 反应 式 模 型 。 第 12 章 总 结 第 
3 部 分 ， 介 绍 如 何 通 过 Spring Data 对 Cassandra 和 Mongo 数 据 库 进 行 读 
写 ， 实 现 反 应 式 数据 持久 化 。 


第 10 章 ”理解 反应 式 编 程 


。 反应 式 编程 概 史 


。 Reactor 项 目 人 简介 


。 有 反应 式 地 处 理 数 据 





你 兽 有 过 订阅 报纸 或 者 森 志 的 经 历 吗 ? 互联 网 的 确 从 传统 的 出 版 友 
行商 那儿 分 得 了 一 杯 绝 ， 但 是 过 去 订阅 报纸 真 的 是 我 们 了 解 时 事 的 最 佳 
方式 。 那 时 ， 我 们 每 天 早上 痢 会 收 到 一 份 新 钙 出 炉 的 报纸 ， 并 在 早饭 时 
间或 上 班 路 上 阅读 。 


现在 假设 一 下 ， 在 文 付 完 订阅 费用 之 后 ， 几 天 的 时 间 过 去 了 ， 你 却 
没有 收 a 到 任何 报纸 。 叉 过 了 几 天 ， 你 打 电 话 给 报社 的 铀 售 部 门 询 问 为 什 
么 还 没有 收 到 报纸 。 想 象 一 下 ， 如 来 他 们 告诉 你 :“ 因 为 你 支付 的 十 一 
整 年 的 订阅 颖 用 ， 而 现在 这 一 年 还 没有 结束 ， 当 这 一 年 结束 时 ， 你 肯定 
可 以 一 次 性 完整 地 收 到 它们 。” 那 么 你 会 有 多 么 惊讶 。 


值得 庆 对 的 是 ， 这 并 非 订 阅 的 真正 运作 方式 。 报 纸 具 有 一 定 的 时 效 
性 。 在 出 版 后 ， 报 纸 需 要 及 时 投递 ， 以 确保 在 阅读 它们 时 内 容 仍然 是 新 
鲜 的 。 此 外 ， 当 你 在 阅读 最 新 一 期 的 报纸 时 ， 记 者 们 正在 为 未 来 的 版 本 
扔 写 内 容 ， 同 时 印刷 机 正在 满 速 运转 ， 印 刷 下 一 期 的 内 容 一 一 一 切 痢 是 
并 行 的 ， 


在 开 友 应 用 程序 代码 时 ， 我 们 可 以 编 与 两 种 风格 的 代码 ， 即 命令 却 
和 反应 式 。 


。 命令 式 〈Imperative〉 的 代码 : 非常 类 似 于 上 文 所 提 的 虚构 的 报纸 

订阅 方式 。 它 由 一 组 任务 组 成 ， 每 次 只 运行 一 项 任务 ， 每 项 任务 义 
都 依赖 于 前 面 的 任务 。 数 据 会 控 批 次 进行 处 理 ， 在 前 一 项 任务 还 没 
有 完成 对 当前 数据 批 次 的 处 理 时 ， 不 能 将 这 些 数 据 递 交 给 下 一 项 处 
理 任务 。 

反应 式 〈Reactive) 的 代码 : 非常 类 似 于 真实 的 报纸 订阅 方式 。 它 

定义 了 一 组 用 来 处 理 数据 的 任务 ， 但 是 这 些 任务 可 以 并 行 地 执行 。 

每 项 任务 处 理 数 据 的 一 部 分 子 集 ， 并 将 结果 交 给 处 理 流程 中 的 下 一 
项 任务 ， 同 时 继续 处 理 数 据 的 另 一 部 分 子 集 。 


在 本 间 中 ， 我 们 将 暂 别 Taco Cloud 应 用 程序 ， 转 而 探索 Reactor 项 
月 。Reactor 是 一 个 有 反应 式 编 程 库 ， 同 时 也 是 Spring 家 族 的 一 部 分 。 它 是 
Spring 5 反应 云 编程 功能 的 基础 ， 所 以 在 我 们 学 习 使 用 Spring 构建 反应 去 
控制 器 和 repository 之 前 ， 理 解 Reactor 是 非常 重要 的 。 不 过 ， 在 我 们 开 
侣 学 习 Reactor 之 前 ， 偿 需要 化 点 时 间 研 究 一 下 反应 式 编 程 的 基本 要 系 。 


10.1 反应 式 编 程 概 哆 


反应 却 编 程 是 一 种 可 以 蔡 代 命令 却 编 程 的 编程 范式 。 这 种 可 苦 代 性 
存在 的 原因 在 于 反应 式 编程 解决 了 命令 式 编程 中 的 一 些 限制 。 理 解 这 些 
限制 ， 有 助 于 你 更 好 地 理解 反应 式 编程 模型 的 优 后 。 


注意 : 反应 式 编 程 不 是 银 弹 。 你 不 应 该 从 这 一 间或 者 其 他 任 
何 关 于 反应 式 编程 的 讨论 中 得 出 “命令 式 编程 是 邪恶 的 ， 而 反应 
却 编 程 才 是 你 的 救星 ?的 结论 。 如 同 我 们 作为 开 肥 者 学 习 到 的 任 


何 技术 一 样 ， 反 应 陈 编程 对 于 条 些 使 用 场景 来 说 的 确 是 完美 的 ， 
但 是 在 其 他 的 一 些 场景 中 可 能 不 那么 适用 。 建 议 以 实用 主义 为 
ee 





如 果 你 和 我 以 及 绝 大 多 数 的 开 友 者 一 样 ， 是 从 命令 式 编程 开始 入 行 
的 ， 那 么 很 可 能 你 现在 编写 的 大 部 分 《或 者 所 有 ) 代码 在 将 来 依然 是 命 
令 式 的 。 命 令 式 编程 相当 和 耻 观 ， 没 有 编程 经 验 的 学 生 们 可 以 在 学 校 的 
STEM 教育 诛 程 中 轻松 地 学习 它 ， 而 且 下 够 临 大 。 在 张 动 大 型 企业 运行 
的 代码 中 ， 绝 大 部 分 部 是 命令 式 的 。 


它 的 理念 很 镜 单 : 你 可 以 一 次 一 个 地 控 照 顺序 将 代码 编写 为 需要 这 
循 的 指令 列表 。 在 东 项 任务 开始 执行 之 后 ， 程 序 在 开始 下 一 项 任务 之 前 
需要 等 待 当 前 任务 完成 。 在 整个 处 理 过 程 中 的 每 一 步 ， 要 处 理 的 数据 都 
必须 是 完全 可 用 的 ， 以 便 将 它们 作为 一 个 整体 进行 处 理 。 


一 开始 一 切 都 很 痿 好 ， 直 到 我 们 过 到 问题 。 在 执行 一 项 任务 的 时 


候 ， 特 别 是 IO 任务 (将 数据 写 入 DB 或 者 从 远程 服务 器 获取 数据 ) ， 
触 友 这 项 任务 的 线程 实际 上 十 补 阻 瑟 的 ， 在 任务 完成 之 前 它 不 能 做 任何 
事情 。 坦 日 来 襄 ， 阻 窟 线程 是 一 种 浪费 。 


大 多 数 编程 语言 (包括 Java)〉 部 文 持 并 发 编程 。 在 Java 中 创建 一 个 
线程 ， 然 后 让 它 执 行 菜 些 操作 ， 而 调用 线程 继续 执行 其 他 工作 ， 这 是 相 
当 容 易 实 现 的 。 虽 然 创 建 线 程 很 简单 ， 但 是 这 些 线程 多 半 最 终 会 家 阴 
考 。 管 理 多 线程 中 的 并 及 极 基 挑战， 而 更 多 线程 则 意味 着 更 多 的 复杂 


| E 
O 


相 比 之 下 ， 反 应 却 编 程 本 质 上 是 函 数 式 的 和 声明 却 的 。 相 对 于 摘 述 
一 组 将 依次 执行 的 步骤 ， 反 应 式 编程 摘 述 了 数据 将 会 流 经 的 管道 或 者 
沉 。 相 对 于 要 求 将 被 处 理 的 数据 作为 一 个 整体 进行 处 理 ， 反 应 式 流 可 以 
在 数据 可 用 时 立即 开始 处 理 。 实 际 上 ， 传 入 的 数据 可 能 是 无 限 的 〈 比 
如 ， 一 个 某 个 地 理 位 置 的 实时 温度 测量 数据 的 恒定 流 ) 。 


拿 现 实 世 界 类 比 一 下 ， 可 以 将 命令 式 编程 看 作 古 水 气球 ， 而 将 反应 
式 编程 看 作 古 化 园 里 的 软 害 。 在 眉 天 ， 这 两 者 部 古 偷 认 和 愉悦 胎 无 戒心 
的 朋友 的 好 方式 ， 但 是 它们 的 运作 方式 却 不 同 : 


。 水 气球 只 能 一 次 性 地 项 满 有 效 载 傈 ， 并 在 措 到 目标 时 卉 湿 对 象 。 水 
气球 的 容量 有 限 ， 如 条 你 想 要 弄 湿 更 多 人 《或 者 把 同一 个 人 和 卉 得 更 
加 湿 透 一 点 ) ， 那 么 唯一 的 选择 融 是 增加 水 气球 的 数量 。 

。 化 园 软 宫 的 有 效 载 衙 是 从 水 龙头 到 喷 路 的 水 流 。 在 特定 的 时 间 氮 ， 
化 园 软 党 的 容量 可 能 是 有 限 的 ， 但 是 在 打 水 仗 的 过 程 中 它 的 容量 却 
是 无 限 的 。 只 要 水 源源 不 断 地 从 龙 尖 流入 软 官 中 ， 水 整 会 源源 不断 


地 从 喷 踢 喷 出 去 。 同 一 个 软 管 非 钊 好 扩展 ， 你 可 以 尽情 地 和 更 多 的 

朋友 打 水 仗 。 

虽然 水 气球 (或 者 命令 式 编程 ) 没有 什么 固有 的 问题 ， 但 是 持 有 和 软 
党 〈 或 者 能 够 应 用 反应 式 编程 ) 的 人 通 锚 在 伸缩 性 和 性 能 方面 更 具 优 


势 。 
定义 反应 式 流 


反应 去 流 (Reactive Streams) 是 由 Netflix、Lightbend 和 和 
Pivotal (Spring 背 后 的 公司 的 工程 师 于 2013 年 年 压 开 始 制 定 的 一 种 规 
沁 。 肥 应 式 沈 时 在 提供 无 阻 窗 回 压 的 寞 步 法 处 理 标准 。 


我 们 已 经 触及 了 反应 式 编程 的 异步 特 性 ， 它 使 我 们 能 够 并 行 执行 任 
务 ， 从 而 实现 更 高 的 可 伸缩 性 。 通 过 回 压 ， 数 据 消 费 痢 可 以 限制 它们 力 
要 处 理 的 数据 数量 ， 避 人 免 被 过 快 的 数据 源 所 济 没 。 


Java 鸭 流 和 反应 式 流 


Java 的 汶 和 反应 陈 流 之 间 有 很 多 相似 之 处 。 首 先 ， 它 们 的 名 
字 中 都 有 流 〈Stream) 这 个 词 。 它 们 还 提供 了 用 于 处 理 数 据 的 函 


数 式 API。 事实 上 ， 正 如 你 稍 后 将 会 在 我 们 介绍 Reactor 时 看 到 的 
那样 ， 它 们 其 至 可 以 共 圣 许多 相同 的 操作 。 


Java 的 流通 各 都 是 同步 的 ， 并 且 只 能 处 理 有 限 的 数据 集 。 从 





本 质 上 来 说 ， 它 们 只 是 使 用 函数 来 对 集合 进行 迁 代 的 一 种 方式 。 


反应 式 流 文 持 寞 步 处 理 任意 大 小 的 数据 集 ， 同 样 也 包括 无 限 
数据 集 。 只 要 数据 就 红 ， 它 们 束 能 实时 地 处 理 数据 ， 并 且 能 够 通 


过 回 压 来 避免 压 葵 数据 的 消 灾 者 。 





反应 式 流 规范 可 以 总 结 为 4 个 接口 : Publisher、Subscriber、 
Subscription 和 Processor。Publisher 负 贡生 成 数据 ， 并 将 数据 发 送 给 
Subscription (每 个 Subscriber 对 应 一 个 Subscription) 。Publisher 接 口 声 明 
了 一 个 方法 subscribe()，Subscriber 可 以 通过 该 方法 同 Publisher 发 起 订 
阅 。 


public interface Publisher<T> { 
void subscribe(Subscriberx<? super T> subscriber); 


} 


一 旦 Subscriber 订 疝 成 功 ， 束 可 以 接收 来 目 Publisher 的 事件 。 这 些 事 
件 是 通过 Subscriber 接 口上 的 方法 发 送 的 : 


interface Subscriber<T> { 
onSubscribe(Subscription sub); 
onNext(T Item ) ; 


onError(Throwable ex ) ; 
onCompletel ) ; 





Subscriber 的 第 一 个 事件 是 通过 对 onSubscribe() 方 法 的 调用 接收 的 。 
Publisher 调 用 onSubscribe() 方法 时 ， 会 将 Subscription 对 象 传递 给 
Subscriber。 通 过 Subscription，Subscriber 可 以 管理 其 订阅 情况 : 


public Interface Subscription { 
void request(long n); 


void cancel(); 





} 


Subscriber 可 以 通过 调用 requestO 方 法 来 请 求 Publisher 及 送 数据 ， 
或 者 通过 调用 cancel0 方 法 表明 它 不 再 对 数据 感 兴趣 并 且 取 消 订 阅 。 当 
调用 request() 时 ，Subscriber 可 以 传 入 一 个 long 类 型 的 数值 以 表明 它 愿意 
接 党 多 少数 据 。 这 也 是 回 压 能 够 及 挥 作用 的 地 方 ， 以 避免 Publisher 友 达 
多 于 Subscriber 能 够 处 理 的 数据 量 。 在 Publisher 发 送 完 所 请 求 数量 的 数 
据 项 之 后 ，Subscriber 可 以 再 次 调用 request0) 方 法 来 请 求 更 多 的 数据 。 


Subscriber 请 求 数据 之 后 ， 数 据 克 会 开始 诉 经 反应 陈诚。Publisher 
发 布 的 每 个 数据 项 都 会 通过 调用 Subscriber 的 onNextO0 方 法 递交 给 
Subscriber。 如 果 有 任何 错误 ， 就 会 调用 onError(0) 方 法 。 如 果 Publisher 
没有 更 多 的 数据 ， 也 不 会 继续 产生 更 多 的 数据 ， 那 么 将 会 调用 
Subscriber 的 onComplete() 方 法 来 告知 Subscriber 它 已 经 结束 。 


至 于 Processor 接 口 ， 它 是 Subscriber 和 和 Publisher 的 组 合 ， 如 下 所 示 : 


public interface Processor<T, R> 
extends Subscriber<T>, Publisher<R> 1{} 


当 作 为 Subscriber 时 ，Processor 会 接收 数据 并 以 茶 种 方式 对 数据 进 
行 处 理 。 然 后 它 会 将 角色 转变 为 Publisher， 并 将 处 理 的 结果 发 布 给 它 的 


Subscriber。 


正如 你 所 看 到 的 ， 反 应 式 流 的 规范 非常 人 简单， 很 容易 束 能 想 出 如 何 
构建 一 个 以 Publisher 作 为 开始 的 数据 处 理 管 道 ， 并 让 数据 通过 零 个 或 多 


个 Processor， 然 后 将 最 终结 果 投 递 给 Subscriber。 


然而 ， 友 应 式 激 规范 的 接口 本 映 并 不 文 持 以 函数 式 的 方式 组 成 这 样 
的 流 。Reactor 项 目 是 反应 式 流 规范 的 一 个 实现 ， 提 供 了 一 组 用 于 组 装 反 
应 式 泊 的 函数 式 API。 我 们 将 会 在 后 面 的 内 容 中 看 到 ，Reactor 构 成 了 
Spring 5 反应 却 编 程 模 型 的 基础 。 在 本 章 的 其 余部 分 ， 我 们 将 会 探讨 
(并 且 ， 我 敢 说 这 个 过 程 非常 有 意思 ) Reactor 项 目 。 


10.2 ” 初 识 Reactor 


有 反应 式 编程 要 求 我 们 米 取 和 命令 式 编程 个 一 样 的 思维 方式 。 此 时 我 
们 不 会 再 接 述 每 一 步 要 进行 的 步 又 ， 反 应 式 编程 意味 看 要 构建 数据 将 要 
沉 经 的 管道 。 当 数据 沉 经 管道 时 ， 可 以 对 它们 进行 未 种 形式 的 修改 或 者 
使 用 。 


例如 ， 假 设 我 们 想 要 接受 一 个 瑞 文 人 名 ， 然 后 将 所 有 的 字母 部 转换 
为 大 与 ， 并 用 得 到 的 绩 朱 创建 一 个 问候 消 轧 ， 并 最 终 打印 它 。 使 用 命令 
式 编程 模型 ， 代 人 码 看 起 来 如 下 所 示 : 


String name = "Craig"; 
String capitalName = name.toUpperCase( ) ; 


String greeting = "Hello, + capitalName + “"!') 
System.out.println(greeting); 





使 用 命令 式 编程 模型 ， 每 行 代码 执行 一 个 步 又， 按部就班 ， 并 且 肯 
定 在 同一 个 线程 中 进行 。 每 一 步 在 执行 完成 之 前 都 会 阻止 执行 线程 执行 


下 一 步 。 


与 乙 不 同 ， 如 下 的 函数 芭 、 反 应 云 代 人 码 完 成 了 相同 的 事情 : 


Mono.just("Craig") 
.map(n -> n.toUpperCase()) 


.map(cn 三 演 "Hello, [a 于 Cn 十 "1") 
.Subscribe(System.out::println); 





不 用 过 上 度 天 心 这 个 例子 中 的 细 市 ， 我 们 很 快 将 会 评 细 讨论 just()、 
map() 和 subscribe() 方法 。 现 在 ， 重 要 的 是 要 理解 : 虽然 这 个 反应 式 的 例 
子 看 起 来 依然 体 持 看 按 步 又 执 行 的 模型 ， 但 实际 是 数据 会 诉 经 处 理 管 
线 。 在 处 理 稼 线 的 每 一 步 ， 都 对 数据 进行 了 荣 种 形式 的 加 工 ， 但 是 我 们 


不 能 判断 数据 会 在 哪个 线程 上 执行 操作 。 它 们 既 可 能 在 同一 个 线程 ， 也 
可 能 在 不同 的 线程 。 


这 个 例子 中 的 Mono 古 Reactor 的 两 种 核心 类 型 之 一 ， 为 一 个 类 型 是 
Flux。 两 者 都 实现 了 反应 式 流 的 Publisher 接 口 。Flux 代 表 有 具有 零 个 、 一 
个 或 者 多 个 《可 能 是 无 限 个 ) 数据 项 的 管道 。Mono 是 一 种 特殊 的 反应 
式 类 型 ， 针 对 数据 项 不 超过 一 个 的 场景 ， 它 进行 了 优化 。 


Reactor 与 RxJava (ReactiveX) 的 对 比 


如 果 你 熟悉 RxJava 或 者 ReactiveX， 那 么 你 可 能 认为 Mono 和 
Flux 类 似 于 Observable 和 Single。 事 实 上 它们 不 仅 在 语义 上 大 致 


相同 ， 还 共 圣 了 很 多 相同 的 操作 从。 


虽然 我 们 在 本 书 中 主要 介绍 Reactor， 但 是 Reactor 和 RxJava 
的 类 型 可 以 互相 转换 ， 我 相信 你 对 这 一 点 会 感到 很 开心 。 其 至 ， 





在 接 下 来 的 章节 中 我 们 还 会 看 到 ，Spring 也 可 以 使 用 RxJava 的 次 
型 。 





实际 上 ， 在 前 面 的 例子 中 有 3 个 Mono。 其 中 ，justO 操作 创建 了 第 
一 个 Mono。 当 该 Mono 及 送 一 个 值 的 时 候 ， 这 个 值 被 传递 给 了 将 字母 转 
换 为 大 写 的 mapO 操 作 ， 据 此 又 创建 了 另 一 个 Mono。 当 第 二 个 Mono 发 布 
它 的 数据 时 ， 数 据 航 传递 给 了 第 二 个 map0O 操 作 ， 并 且 会 在 此 进行 一 些 
字 从 串 连 接 操 作 ， 而 结果 将 用 于 创建 第 三 个 Mono。 最 后 ， 对 第 三 个 
Mono 上 的 subscribe() 方 法 调用 时 ， 会 接收 数据 并 将 数据 打印 出 来 。 


10.2.1 绘制 反应 式 流 图 


反应 式 流程 通常 使 用 弹 珠 图 (marble diagram) 表示 ， 如 图 10.1 所 
示 。 弹 珠 图 的 展现 形式 非常 向 蛙 ， 在 顶部 插 述 了 数据 沉 经 Flux 或 者 
Mono 的 时 间 线 ， 在 中 间 摘 述 了 要 执行 的 操作 ， 在 搬 部 插 述 了 结 来 形成 
的 Flux 或 者 Mono 的 时 间 线 。 我 们 将 会 看 到 ， 妆 数据 法 经 原始 的 Flux 时 ， 
东 些 操作 将 会 对 它 进 行 处 理 ， 并 产生 一 个 新 的 Flux， 已 经 处 理 过 的 数据 
将 会 在 新 Flux 中 流动 。 


4 
Flux 的 时 间 线 一 一 ~ HOO@@ 


在 Flux 上 进行 


通过 对 原始 的 Flux | | I | 


进行 某 种 操作 而 产 l 
生 的 新 的 Flux 
| 标记 Flux 发 生 错 误 或 者 异常 终止 


在 操作 执行 之 后 ， 在 
新 的 Flux 上 流动 的 值 





图 10.1 ”描绘 Flux 基 本 流程 的 弹 珠 图 


图 10.2 展 示 了 一 个 类 似 的 弹 珠 图 ， 但 是 针对 的 是 Mono。 我 们 可 以 看 
到 ， 这 里 主要 的 不 同 是 Mono 将 会 有 零 个 或 者 一 个 数据 项 ， 或 者 一 个 错 
1 
由 Mono 发 布 的 一 个 值 标记 Mono 的 完成 


Mono 的 时 间 线 一 一 = 


在 Mono 上 进行 


通过 对 原始 的 Mono ， ， 
进行 某 种 操作 而 产生 
的 新 的 Mono 
在 操作 执行 之 后 ,在 新 人 | 
的 Mono 上 流动 的 值 





标记 Mono 发 生 错误 
或 者 异常 终止 


图 10.2” 摘 绘 Mono 基 本 流程 的 弹 珠 图 


在 10.3 节 ， 我 们 将 会 探索 Flux 和 Mono 支 持 的 许多 操作 ， 同 时 我 们 还 
将 使 用 弹 珠 图 来 可 视 化 它们 的 工作 原理 。 


10.2.2” 湛 加 Reactor 依 正 


要 开始 使 用 Reactor， 请 将 下 面 的 依赖 项 添加 到 项 目的 构建 文件 中 : 


<dependency> 
<groupId>io.projectreactor</groupId> 


<artifactId>reactor-core</artifactId> 
</dependency> 





Reactor 还 提供 了 非常 棒 的 测试 支持 。 我 们 将 会 围 纯 Reactor 代 码 编 
与 大 量 的 测试 ， 因 此 绝对 需要 将 下 面 的 依赖 洪 加 到 构建 文件 中 : 


<dependency> 
<groupId>io.projectreactor</groupId> 
<artifactId>reactor-test</artifactId> 
<SCOpey>test</scopey> 

</dependency> 





如 末 你 计划 将 这 些 依赖 添加 到 一 个 Spring Boot 工 程 中 ， 那 么 Spring 
Boot 工 程 会 蔡 你 党 理 依赖 。 但 是 ， 如 采 要 在 非 Spring Boot 项 目 中 使 用 
Reactor， 束 需要 在 构建 文件 中 设置 ReactorHJBOM (Bill Of Materials， 
物料 清单 ) 。 下 和 面 的 依赖 害 理 条 目 将 会 把 Reactor 的 Bismuth 版 本 添加 到 
构建 文件 中 : 

<dependencyManagement> 
<dependencies> 
<dependency> 


<groupId>io.projectreactor</groupId> 
<artifactId>reactor-bom</artifactId> 


<version>Bismuth-RELEASE</version> 
<type>pom</type> 
<scope>import</scope> 
</dependency> 
</dependencies> 
</dependencyManagement> 





现在 Reactor 已 经 位 于 工程 的 构建 文件 中 了 ， 我 们 可 以 开始 使 用 
Mono 和 了 Flux 来 创建 反应 式 的 处 理 管 线 。 在 本 章 的 剩余 部 分 ， 我 们 将 介 
绍 Mono 和 Flux 所 提供 的 几 个 操作 。 


10.3 ”使 用 常见 的 反应 式 操 作 


Flux 和 Mono 古 Reactor 提 供 的 最 基础 的 构建 块 ， 而 这 两 种 反应 式 类 
型 所 提供 的 操作 符 则 是 组 合 使 用 它们 以 构建 数据 流动 管线 的 荞 合剂 。 
Flux 和 Mono 共 有 500 多 个 操作 ， 这 些 操 作 都 可 以 大 致 归 类 为 : 


。 创建 操作 ; 
。 组 合 操 作 ; 
。 转 的 操作 ; 
。 也 辑 操 作 。 


虽然 对 这 500 多 个 操作 一 一 探讨 会 非常 有 趣 ， 但 是 本 章 的 视 幅 有 
了 眼 ， 所 以 我 在 本 节 中 选择 一 些 有 用 的 操作 来 进行 次 明 。 下 面 让 我 们 从 创 
建 操作 开始 吧 。 


注意 : Mono 的 例子 呢 ? 因为 Mono 和 Flux 的 很 多 操作 是 相同 
的 ， 所 以 没有 必要 针对 Mono 和 Flux 重 复 进 行 介绍 。 此 外 ， 虽 然 
Mono 的 操作 也 很 有 用 ， 但 是 相 比 而 言 ，Flux 上 的 操作 更 有 趣 。 


我 们 的 大 多 数 示 例会 使 用 Flux。 读 者 只 需要 知道 Mono 上 通常 具 
有 相同 的 名 称 的 操作 即 可 。 





10.3.1 创建 反应 式 类 型 


在 Spring 中 使 用 反应 式 类 型 上 时， 我 们 通 委 将 会 从 repository 或 者 
service 中 获取 Flux 或 Mono， 并 不 需要 我 们 目 行 创建 。 倘 尔 ， 我 们 可 能 需 
要 创建 一 个 新 的 反应 式 Publisher。 


Reactor 提 供 了 多 种 创建 Fux 和 Mono 的 操作 。 这 里 ， 我 们 将 介绍 其 
中 一 些 有 用 的 创建 操作 。 


根据 对 象 创建 


如 果 你 有 一 个 或 多 个 对 象 ， 并 想 据 此 创建 Flux 或 Mono， 那 么 可 以 
使 用 Flux 或 Mono 上 的 静态 justO 方 法 来 创建 一 个 反应 式 炎 型， 它们 的 数 
据 会 由 这 些 对 象 来 驱动 。 例 如 ， 下 面 的 测试 方法 将 从 5 个 String 对 象 中 创 
建 一 个 Flux: 

QTest 


public void createAFlux just() { 
Flux<String> fruitFlux = Flux 


.just("Apple", "Orange", "Grape", "Banana", "Strawberry"); 





} 


此 时 我 们 已 经 创建 了 Flux， 但 是 它 还 没有 订阅 者 。 如 来 没有 任何 的 
订阅 者 ， 那 么 数据 将 不 会 流动 。 回 想 一 下 人 花园 软 管 的 比喻 ， 假 设 我 们 已 
经 将 化 园 软 过 连接 到 了 水 龙头 上 ， 画 一 侧 是 水 广 的 水 一 一 但 是 在 你 打开 
水 龙头 之 前 ， 水 不 会 流动 。 订 阅 有 反应 式 类 型 束 如 同 你 打开 数据 流 的 水 龙 


要 添加 一 个 订阅 者 ， 我 们 可 以 在 Flux 上 调用 subscribe() 方 法 : 


fruitFlux.subscribel 


f -> System.out.println("Here's some fruit: ”+ f) 


) 





这 里 传递 给 subscribe() 方 法 的 lambda 表 达 式 实际 上 是 一 个 
java.util.Consumer， 用 来 创建 反应 式 流 的 Subscriber。 在 调用 subscribe() 
之 后 ， 数 据 会 开始 流动 。 在 这 个 例子 中 ， 没 有 有 中间 操 作 ， 所 以 数据 从 
Flux 和 直接 流 同 订阅 者 。 


将 来 和 目 Flux 或 Mono 的 数据 项 打印 到 控制 台 是 观察 反应 式 交 型 运行 
方式 的 好 方法 ， 实 际 测试 Flux 或 Mono 更 好 的 方法 是 使 用 Reactor 提 供 的 
StepVerifier。 对 于 给 定 的 Flux 或 Mono，StepVerifier 将 会 订阅 该 反应 式 类 
型 ， 在 数据 流 过 时 对 数据 应 用 电 言 ， 并 在 最 后 验证 反应 式 流 是 任 按 预期 
成 。 


dl 


例如 ， 要 验证 预定 义 的 数据 是 合流 经 了 fruitFlux， 我 们 可 以 编号 如 
下 所 示 的 测试 代码 : 
StepVerifier.create(fruitFlux) 


.expectNext("Apple") 
.expectNext("Orange") 


.expectNext("Grape") 
.expectNext("Banana") 
.expectNext("Strawberry") 
.verifyComplete( ) ; 





在 这 个 例子 中 ，StepVerifier 订 向 了 fruitFlux， 然 后 断言 Flux 中 的 
个 数据 项 是 人 否 与 预期 的 水 果 名 称 相 匹配 。 最 后 ， 它 验证 Flux 和 在 发 布 


完 “Strawberry” 之 后 ， 整 个 fruitFlux 下 常 完成 。 


对 于 本 间 的 其 他 例子 ， 你 可 以 使 用 StepVerifier 来 编写 测试 ， 验 证 
Flux 或 者 Mono 行 为 ， 人 研究 相应 的 工作 原理 ， 从 而 帮助 你 学 习 和 和 了解 
Reactor 中 最 有 用 的 操作 。 


根据 集合 创建 


我 们 还 可 以 根据 数组 、Iterable 或 者 Java Stream 创 建 Flux。 图 10.3 使 
用 弹 珠 图 展示 如 何 使 用 这 种 方式 进行 创建 。 


OQ@OOO@O©e©. 
fromArray, fromlterable, fromStream 
| | ! | | | 





图 10.3 ”可 以 根据 数组 、Tterable 或 者 Java Stream 创 建 Flux 


要 根据 数组 创建 Flux， 可 以 调用 Flux 上 的 静态 方法 fromArray()， 并 
传 入 一 个 源 数 组 : 





@Test 
public void createAFlux fromArray() { 
String[] fruits = new String[] { 
"Apple", "Orange", "Grape", "Banana", ”Strawberry ” }; 


Flux<String> fruitFlux = Flux.fromArray(fruits); 


StepVerifier.create(fruitFlux) 
.expectNext("Apple") 
.expectNext ("Orange") 
.expectNext("Grape") 
.expectNext("Banana") 
.expectNext("Strawberry") 
.verifyComplete(); 


| 


因为 该 源 数 组 包含 了 之 前 从 对 象 列表 创建 Flux 时 所 使 用 的 相同 的 水 
末 名 称 ， 所 以 该 Flux 发 布 的 数据 会 有 相同 的 伍 ， 可 以 使 用 和 之 前 相同 的 
StepVerifier 来 验证 。 


如 果 我 们 需要 根据 java.util.List、java.util.Set 或 者 其 他 任意 
java.lang.Iterable 的 实现 来 创建 Flux， 那 么 可 以 将 其 传递 给 静态 的 
fromlterable() 方 法 : 


@Test 

public void createAFlux_fromIterable() { 
List<String> fruitList = new ArrayList<>(); 
fruitList.add("Apple" ); 
fruitList.add("Orange"); 
fruitList.add("Grape" ); 


fruitList.add("Banana" ); 
fruitList.add("Strawberry"); 


Flux<String> fruitFlux = Flux.fromIterable(fruitList); 


// ... verify steps 





或 者 ， 我 们 有 一 个 Java Stream， 并 且 和 希望 将 其 用 作 Flux 的 源 ， 那 么 
可 以 调用 fromStream0) 方 法 : 


QTest 
public void createAFlux fromStream() { 
Stream<String> fruitStream = 
Stream.of("Apple", "Orange", "Grape", "Banana", "Strawberry"); 


Flux<String> fruitFlux = Flux.fromStream(fruitStream); 


// ... verify steps 
} 





同样 ， 我 们 可 以 使 用 和 之 前 一 样 的 StepVerifier 来 验证 该 Flux 发 布 的 
数据 。 


生成 Flux 的 数据 


有 时 候 我 们 根本 没有 可 用 的 数据 ， 而 只 是 想 要 一 个 作为 计数 喜 的 
Flux， 它 会 在 每 次 发 送 新 值 时 增加 1。 要 创建 一 个 计数 占 Flux， 我 们 可 以 
使 用 静态 方法 range()。 图 10.4 说 明了 range() 方 法 的 工作 原理 。 


range(n, m) 
ee-ce 上 - 
图 10.4 ”从 区 间 创 建 的 Flux 会 以 类 似 计数 占 的 方式 发 布 消 忆 
下 面 的 测试 方法 展示 了 了 如何 创 建 一 个 区 间 Flux: 


QTest 
public void createAFlux range() { 
Flux<Integer> intervalFflux = 
Flux.range(1, 5); 
StepVerifier.create(intervalFlux) 
.expectNext(1) 


.expectNext (2) 
.expectNext(3) 
.expectNext(4) 
.expectNext(5) 
.verifyComplete( ) ; 





在 这 个 例子 中 ， 我 们 创建 了 一 个 区 间 Flux， 起 始 值 为 1， 结 束 值 为 
5。StepVerifier 证 明了 它 将 发 布 5 个 条 目 ， 即 整数 1 到 5。 


男 一 个 与 range0 方 法 类 似 的 Flux 创 建 方法 古 interval()。 与 range0 方 
法 一 样 ，interval0) 方 法 会 创建 一 个 发 布 违 增值 的 Flux。interval0 的 特殊 
之 处 在 于 ， 我 们 不 是 给 它 设置 一 个 起 始 什 和 结束 什 ， 而 是 指定 一 个 应 该 
每 隔 多 长 时 间 发 出 值 的 间隔 时 间 。 图 10.5 展 示 了 interval0 方 法 创建 Flux 
的 弹 珠 图 。 


interval( © 





图 10.5 ”根据 指定 间隔 创建 的 Flux 会 周期 性 地 及 布 条 目 


例如 ， 妥 创建 一 个 每 秒 发 布 一 个 值 的 Flux， 你 可 以 使 用 Flux 上 的 语 
人 态 interval() 方法 ， 如 下 所 示 : 


QTest 
public void createAFlux interval() { 
Flux<Long> intervalFflux = 
Flux.interval(Duration.ofSeconds(1)) 
.take(5); 


StepVerifier.create(intervalFlux) 


.expectNext (8L) 
.expectNext (1L) 
.expectNext (2L) 
.expectNext (3L) 
.expectNext (4L) 
.verifyComplete( ) ; 





需要 注意 的 是 ， 通 过 interval0) 方 法 创建 的 Flux 会 从 0 开始 发 布 值 ， 并 
且 后 续 的 条 目 依 次 递增 。 此 外 ， 因 为 interval0) 方 法 没有 指定 最 大 值 ， 所 
以 它 可 能 会 永远 运行 。 我 们 也 可 以 使 用 take() 方 法 将 结果 限制 为 前 5 个 条 


目 。 我 们 将 在 下 一 和 中 详细 讨论 take0) 方 法 。 


10.3.2 组合 反应 式 类 型 


有 了 时候 ， 我 们 会 需要 操作 两 种 反应 式 类 型 ， 并 以 某 种 方式 将 它们 合 
并 在 一 起 。 或 者 ， 在 其 他 情况 下 ， 我 们 可 能 需要 将 Flux 拆 分 为 多 种 反应 
去 类 型 。 在 本 和 中 ， 我 们 将 研究 组 合 以 及 拆 分 Reactor 的 Flux 和 Mono 的 
操作 。 


合并 反应 式 类 型 


假设 我 们 有 两 个 Flux 流 ， 并 且 需 要 据 此 创建 一 个 结 末 Flux， 这 个 形 
成 的 Flux 会 在 任 章 上 游 Flux 流 有 数据 时 产生 数据 。 要 将 一 个 Flux 与 为 一 
个 Flux 合 并 ， 可 以 使 用 mergeWithO 方 法 ， 如 图 10.6 中 的 弹 珠 图 所 示 。 





图 10.6 ”合并 两 个 Flux 流 《它们 的 消息 将 会 交错 合并 为 一 个 新 的 Flux) 
例如 ， 假 设 有 一 个 值 是 电视 和 电影 角色 名 称 的 Flux， 还 有 为 一 个 值 
是 这 些 角 色 喜 欢 吃 的 食物 的 名 称 的 Flux。 下 面 的 测试 方法 展示 了 如 何 使 
用 mergeWith0) 方 法 合并 两 个 Flux 对 象 : 


QTest 
public void mergeFluxes() { 


Flux<String> characterFlux = Flux 
.just("Garfield", "Kojak", "Barbossa") 
.delayElements(Duration.ofMillis(560)); 

Flux<String> foodFlux = Flux 
.just("Lasagna", "Lollipops", "Apples") 
.delaySubscription(Duration.ofMillis(2508)) 
.delayElements(Duration.ofMillis(5060)); 


Flux<String> mergedFlux = characterFlux.mergeWith(foodFlux); 


StepVerifier.create(mergedFlux) 
.expectNext("Garfield") 
.expectNext("Lasagna") 
.expectNext ("Kojak") 
.expectNext("Lollipops") 
.expectNext("Barbossa") 
.expectNext("Apples") 
.verifyComplete(); 





通常 ，Flux 会 尽 可 能 快 地 有 友 布 数据 。 因 此 ， 我 们 在 创建 的 两 个 Flux 
流 上 使 用 delayElements0) 方 法 来 减 慢 它们 的 速度 友 布 二 小 
条 目 。 此 外 ， 为 了 使 食物 Flux 在 角色 名 称 Flux 之 后 再 开始 流 陈 传输 ， 我 
们 调用 了 食物 Flux 上 的 delaySubscription0) 方 法 ， 以 便 它 在 订阅 后 再 经 过 
250 坚 秒 后 才 开 始 及 布 数据 。 


一 
上 ;A 











在 合并 了 两 个 Flux 对 象 后 ， 将 会 创建 一 个 新 的 合并 过 后 的 Flux。 当 
StepVerifier 订 哆 这 个 合并 过 后 的 Flux 时 ， 它 将 依次 订阅 两 个 源 Flux 流 并 
局 动 数 据 沉 。 


这 个 合并 过 后 的 Flux 数 据 项 及 布 顺序 与 源 Flux 的 及 布 时 间 一 致 。 
为 两 个 Flux 对 象 都 设置 为 以 和 营 规 速率 进行 及 布 ， 所 以 这 些 值 在 合并 后 的 
Flux 中 会 交错 在 一 起 ， 结 果 是 : 一 个 角色 、 一 个 食物 、 万 一 个 角色 、 万 


一 个 食物 ， 以 此 类 推 。 如 果 任 何 一 个 Flux 的 计时 发 生变 化 ， 那 么 你 可 能 
会 看 到 接连 发 布 了 两 个 角色 或 者 两 个 食物 。 


因为 mergeWith() 方 法 不 能 完美 地 你 证 源 Flux 之 间 的 先后 顺序 ， 所 以 
我 们 可 以 考虑 使 用 zip0) 方 法 。 当 两 个 Flux 对 象 压 缩 在 一 起 的 时 候 ， 它 将 
会 产生 一 个 新 的 友 布 元 组 的 Flux， 其 中 每 个 元 组 中 都 包含 了 来 日 每 个 源 
Flux 的 数据 项 。 图 10.7 说 明了 如 何 将 两 个 Flux 对 象 压缩 在 一 起 。 





图 10.7 通过 zip0) 方 法 合并 两 个 Flux 尝 


要 但 看 zip0) 操 作 实 际 如 何 运 行 ， 可 以 考虑 如 下 所 示 的 测试 方法 ， 它 
将 角色 Flux 和 食物 Flux 合 并 在 一 起 : 





QTest 
public void zipFluxes() { 
Flux<String> characterFlux = Flux 
.just("Garfield", "Kojak", "Barbossa"); 
Flux<String> foodFlux = Flux 
.just("Lasagna", "Lollipops", "Apples"); 


Flux<Tuple2<String, String>> zippedFlux = 
Flux.zip(characterFlux, foodFlux); 
StepVerifier.create(zippedFlux) 
.expectNextMatches(p -> 
p.getT1().equals("Garfield") && 
p.getT2().equals("Lasagna" )) 
.expectNextMatches(p -> 


p.getT1().equals("Kojak") && 
p.getT2().equals("Lollipops")) 
.expectNextMatches(p -> 
p.getT1().equals("Barbossa") && 
p.getT2().equals("Apples")) 
.verifyComplete( ) ; 





需要 注意 的 是 ， 与 mnergeWith(0) 方 法 不 同 ，zip0 方 法 是 一 个 静态 的 创 
建 操作 。 创建 出 来 的 Flux 在 角色 和 他 们 喜欢 的 食物 之 则 会 完美 对 章 。 从 

个 合并 后 的 Flux 发 出 的 每 个 条 目 都 是 一 个 Tuple2 (一 个 容纳 两 个 其 他 
对 象 的 容 絮 对象 ) 的 实例 ， 其 中 包含 了 来 日 每 个 源 Flux 的 数据 项 ， 并 保 
持 看 它们 有 布 的 顺序 。 


ee 而 想 要 使 用 其 他 类 型 ， 就 可 以 为 zip(0) 方 法 
提供 一 个 国 数 来 生成 你 想 要 的 任何 对 象 ， 合 并 函数 会 传 入 这 两 个 数 
据 项 Pain 。 


一 全 一 仿 一 一 一 


zip((( ) ,>--O)) 


图 10.8 zip 操作 的 另 一 种 形式 〈 从 每 个 传 入 Flux 中 各 取 一 个 元 素 ， 
然后 创建 消息 对 象 ， 并 产生 这 些 消息 组 成 的 Flux ) 


例如 ， 和 直面 的 测试 方法 会 将 角色 Flux 与 食物 Flux 合 并 在 一 起 ， 以 便 
生成 一 个 包含 String 对 象 的 Flux: 


QTest 
public void zipFluxesToObject() { 
Flux<String> characterFlux = Flux 
.just("Garfield", "Kojak", "Barbossa"); 
Flux<String> foodFlux = Flux 
.just("Lasagna", "Lollipops", "Apples"); 


Flux<String> zippedFlux = 
Flux.zip(characterFlux, foodFlux, (c, f) ->c+" eats " + f); 


StepVerifier.create(zippedFlux) 
.expectNext("Garfield eats Lasagna") 
.expectNext("Kojak eats Lollipops") 
.expectNext("Barbossa eats Apples") 
.verifyComplete( ) ; 





传递 给 zip() 方 法 〈 在 这 里 是 一 个 lambda) 的 函数 只 是 简单 地 将 两 个 
数据 项 组 闻 成 一 个 名 于， 然后 通过 该 合并 后 的 Flux 肥 布 出 去 。 


选择 第 一 个 反应 式 类 型 进行 及 布 


假设 我 们 有 两 个 Flux 对 象 ， 此 时 我 们 不 想 将 它们 合并 在 一 起 ， 而 古 
想 要 创建 一 个 新 的 Flux， 让 这 个 新 的 Flux 从 第 一 个 产生 值 的 Flux 中 发 布 
值 。 如 图 10.9 所 示 ，first() 操 作 会 在 两 个 Flux 对 象 中 选择 第 一 个 友 布 值 的 
Fluxz， 并 再 次 有 发布 它 的 值 。 








图 10.9 _ first 操作 将 会 选择 第 一 个 发 布 消 息 的 Flux 并 只 发 布 该 Flux 的 值 


下 面 的 测试 方法 创建 了 一 个 快速 的 Flux 和 一个“ 绥 慢 * 的 Flux (其 
中 “ 慢 * 昔 味 看 它 在 被 订 阅 后 100 暑 秒 才 会 友 布 数据 项 ) 。 使 用 first0) 方 
法 ， 它 将 会 创建 一 个 新 的 Flux， 这 个 Flux 只 会 获取 第 一 个 源 Flux 友 布 的 
值 ， 并 肝 座 友 布 : 


QTest 
public void firstFlux() { 
Flux<String> slowFlux = Flux.just("tortoise", "snail", "sloth") 
.delaySubscription(Duration.ofMillis(10680)); 
Flux<String> fastFlux = Flux.just("hare", "cheetah", "squirrel"); 


Flux<String> firstFlux = Flux.first(slowFlux, fastFlux); 


StepVerifier.create(firstFlux) 
.expectNext ("hare") 
.expectNext("cheetah") 
.expectNext("squirrel") 
.verifyComplete(); 





在 这 种 情况 下 ， 因 为 慢 速 Flux 会 在 快速 Flux 开 始 发 布 之 后 的 100 嗓 秒 
才 及 布什 ， 所 以 新 创建 的 Flux 将 会 简单 地 忽略 慢 的 Flux， 并 仅 用 布 来 目 
快速 Flux 有 的 值 。 


10.3.3 ”转换 和 过 滤 反 应 式 流 


在 数据 流 经 一 个 流 时 ， 我 们 通常 需要 过 滤 挥 祭 些 值 并 对 其 他 的 值 进 
行 处 理 。 在 这 一 市 ， 我 们 将 介绍 转换 和 过 渡 流 经 反应 式 尝 的 数据 的 控 
作 。 


从 反应 式 类 型 中 过 渡 数 据 


数据 在 从 Flux 流 出 时 ， 进 行 过 渡 的 最 基本 方法 之 一 古人 简单 地 忽略 第 
一 批 指 定数 目的 数据 项 。skip 操 作 〈( 如 图 10.10 所 示 〉 束 能 完成 这 样 的 工 
作 。 





图 10.10 ”skip 操 作 跳 过 指定 数目 的 消 恩 并 将 剩 下 的 消 居 继续 在 结果 Flux 上 进行 传递 


针对 具有 多 个 数据 项 的 Flux，skip 操 作 将 创建 一 个 新 的 FIux， 它 会 
首先 跳 过 指定 数量 的 数据 项 ， 然 后 从 源 Flux 中 发 布 剩余 的 数据 项 。 下 
面 的 测试 方法 展示 如 何 使 用 skip0 方 法 : 


QTest 
public void skipAFew() { 
Flux<String> skipFlux = Flux.just( 
"one", "two", "skip a few", "ninety nine", "one hundred") 
.Skip(3); 


StepVerifier.create(skipFlux) 
.expectNext("ninety nine", "one hundred") 
.verifyComplete(); 





在 这 个 场景 下 ， 我 们 有 一 个 具有 5 个 String 数 据 项 的 Flux。 在 这 个 
Flux 上 调用 skip(3) 方 法 后 会 产生 一 个 新 的 Flux， 它 会 跳 过 前 3 个 数据 项 ， 
只 及 布 最 后 2 个 数据 项 。 


但 是 ， 你 可 能 并 不 想 跳 过 特定 数量 的 条 目 ， 而 是 想 要 在 一 段 时 间 之 
内 跳 过 所 有 的 第 一 批 数 据 。 这 是 skip0 操 作 的 男 一 种 形式 ， 将 会 产生 一 
个 靳 Flux， 在 发 布 来 日 源 Flux 的 数据 项 之 前 等 每 指定 的 一 段 时 间 ， 如 图 
10.11 所 示 。 





图 10.11 ” skip 操作 的 男 一 种 形式 


下 面 的 测试 方法 使 用 skip 操 作 创 建 了 一 个 在 发 布 值 之 前 会 等 每 4 秒 
Flux。 因 为 Flux 古 基于 一 个 在 发 布 数 据 项 之 间 有 1 秒 延 人 运 的 Flux 创 建 


的 《使 用 了 delayElements0O 操 作 ) ， 所 以 它 只 会 发 布 出 最 后 两 个 数据 
项 : 


QTest 
public void skipAFewSeconds() { 
Flux<String> skipFlux = Flux.just( 
"one", "two", "skip a few", "ninety nine", "one hundred") 
.delayElements(Duration.ofSeconds(1)) 
.Skip(Duration.ofSeconds(4)); 


StepVerifier.create(skipFlux) 
.expectNext("ninety nine", "one hundred") 
.verifyComplete(); 





我 们 已 经 看 过 skip 操 作 的 示例 ， 根 据 对 skip 操 作 的 摘 述 来 看 ，take 可 
以 认为 是 与 skip 相 反 的 操作 。skip 操 作 会 跳 过 前 面 几 个 数据 项 ， 而 take 操 


作 只 友和 布 第 一 批 指 定数 量 的 数据 项 ， 然 后 将 取消 订阅 (如 图 10.12 中 的 
弹 珠 图 所 示 )。 


QTest 
public void take() { 
Flux<String> nationalParkFlux = Flux.just( 
"Yellowstone", "Yosemite", Grand Canyon'", 
"Zion", "Grand Teton") 
.take(3); 


StepVerifier.create(nationalPparkFlux) 
.expectNext("Yellowstone", "Yosemite", "Grand Canyon") 
.verifyComplete( ) ; 








图 10.12 take 操作 只 发 布 传 入 Flux 中 前 面 指定 数目 的 数据 项 
与 skip0 方 法 一 样 ，take() 方 法 也 有 男 一 种 蔡 代 形式 ， 基 于 间隔 时 间 


而 不 是 数据 项 个 数 。 它 将 接受 并 发 布 与 源 Flux 一 样 多 的 数据 项 ， 直 到 某 
段 时 间 结 束 ， 之 后 Flux 将 会 完成 ， 如 图 10.13 所 示 。 





图 10.13 take 操作 的 另 一 种 形式 〈 在 指定 的 时 间 过 期 之 前 ， 一 直 将 消息 传递 给 结果 Flux ) 


下 面 的 测试 方法 使 用 take0) 方 法 的 另 一 种 形式 ， 将 会 在 订阅 之 后 的 
前 3.5 秒 发 布 数据 条 目 。 


QTest 
public void take() { 
Flux<String> nationalParkFlux = Flux.just( 
"Yellowstone", "Yosemite", Grand Canyon  ， 
"Zion", "Grand Teton") 
.delayElements(Duration.ofSeconds(1)) 


.take(Duration.ofMillis(35080)); 


StepVerifier.create(nationalPparkFlux) 
.expectNext("Yellowstone", "Yosemite", "Grand Canyon") 
.verifyComplete( ) ; 





skip 操 作 和 take 操 作 都 可 以 锐 认 为 是 过 小 操作 ， 其 过 小 条 件 是 基于 
计数 或 者 持续 时 间 的 ， 而 Flux 值 的 更 通用 过 小 则 是 filter 操 作 。 


我 们 珊 要 指定 一 个 Predicate， 用 于 决定 数据 项 古 售 能 通过 Flux， 
filter 操 作 人 多 许 我 们 根据 任何 条 件 进行 选择 性 地 及 布 。 图 10.14 中 的 弹 珠 图 
显示 了 filter 操作 的 工作 原理 。 





filter( () 
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图 10.14 ”可 以 对 传 入 的 Flux 进 行 过 小 ， 这 样 结果 Flux 将 只 会 发 布 满足 指定 Predicate 的 消 轧 


要 但 看 filter() 的 实际 效果 ， 可 以 参考 下 面 的 籼 试 方法 : 


@Test 
public void filter() { 


Flux<String> nationalParkFlux = Flux.just( 
"Yellowstone", "Yosemite", Grand Canyon  ， 
"Zion", "Grand Teton") 
.filter(np -> Inp.contains(" ")); 
StepVerifier.create(nationalParkFlux) 
.expectNext("Yellowstone", "Yosemite", "Zion") 
.verifyComplete( ) ; 





这 里 我 们 将 一 个 只 接受 不 包 仿 空格 的 字符 串 的 Predicate 作 为 lambda 
传 给 了 filter0 方 法 ， 因 此 在 结果 Flux 中 "Grand Canyon" 和 "Grand Teton" 被 
过 滤 近 了。 


我 们 还 可 能 想 要 过 渡 挥 已 经 接收 过 的 数据 条 目 ， 可 以 采用 distinct 操 
作 〈 如 图 10.15 所 示 〉， 形 成 的 Flux 将 只 会 发 布 源 Flux 中 沿 未 友 布 过 的 数 
据 项 。 
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图 10.15 distinct 操 作 将 会 过 滤 描 重复 的 消 奶 





在 下 面 的 测试 中 ， 调 用 distinctO 方 法 产生 的 Flux 只 会 友 布 不 同 的 
String 值 : 





QTest 
public void distinct() { 
Flux<String> animalFlux = Flux.just( 
"dog", "cat", "bird", "dog", "bird", "anteater") 
.distinct(); 


StepVerifier.create(animalFlux) 


.expectNext("dog", "cat", "bird", "anteater") 
.verifyComplete(); 





里 然 "dog" 和 "bird" 从 源 Flux 中 部 友 布 了 两 钦 ， 但 是 在 调用 distinct() 方 
法 产生 的 结果 Flux 中 ， 它 们 只 被 发 布 了 一 次 。 


映 味 反应 式 数 据 


在 Flux 或 Mono 上 最 常见 的 操作 之 一 就 是 将 已 发 布 的 数据 项 转换 为 
其 他 的 形式 或 类 型 。Reactor 的 反应 式 类 型 (Flux 和 Mono) 为 此 提供 了 
map 和 flatMap 操 作 。 


map 操 作 会 创建 一 个 新 的 Flux， 只 是 在 重新 发 布 它 所 接收 的 每 个 对 
象 之 前 会 执行 给 定 Function 指 定 的 转换 。map 操 作 的 工作 原理 如 图 10.16 
所 示 。 


I , 1 | | 
图 10.16 ”map 操作 将 传 入 的 消息 转换 为 结果 流 上 的 新 消息 


在 下 面 的 testO 方 法 中 ， 包 舍 代 表 篮 球 运动 员 名 字 的 String 值 的 Flux 
被 转换 为 一 个 包含 Player 对 象 的 新 Flux。 





QTest 
public void map() { 
Flux<Player> playerFlux = Flux 


.just("Michael Jordan", "Scottie Pippen", "Steve Kerr") 
.map(n -> { 

String[|] split = n.split("\\s"); 

return new Player(split[8], split[1]); 
}); 


StepVerifier.create(playerFlux) 
.expectNext(new Player("Michael", "Jordan")) 
.expectNext(new Player("Scottie", "Pippen")) 
.expectNext(new Player("Steve", "Kerr")) 
.verifyComplete( ) ; 





以 ljambda 形 陈 传 递 给 map0) 方 法 的 函数 会 将 传 入 的 String 值 投 照 衬 
进行 拆 分 ， 并 使 用 生成 的 String 数 组 来 创建 Player 对 象 。 使 用 justO 方 法 创 
建 的 Flux 包 含 了 String 对 象 ， 但 是 map0 方 法 产生 的 Flux 包 含 了 Player 对 
象 。 


其 中 重要 的 一 点 是 ， 在 每 个 数据 项 被 源 Flux 发 布 时 ，map 操 作 是 同 
步 执行 的 ， 如 果 你 想 要 异步 地 转换 过 程 ， 那 么 你 应 该 考虑 使 用 flatMap 操 
作 。 


对 于 flatMap 操 作 ， 我 们 可 能 需要 一 些 思 考 和 练习 才能 完全 营 握 。 如 
图 10.17 所 示 ，flatMap 并 不 像 map 操 作 那 样 稍 单 地 将 一 个 对 象 转换 到 另 一 
个 对 象 ， 而 是 将 对 象 转换 为 新 的 Mono 或 Flux。 结 果 形 成 的 Mono 或 Flux 
会 局 平 化 为 新 的 Flux。 当 与 subscribeOn0) 方 法 结合 使 用 时 ，flatMap 操 作 
可 以 释放 Reactor 反 应 式 的 异步 能 力 。 





flatMap( (OO) - 上 二 >) 





图 10.17 ”flatMap 操 作 使 用 一 个 中 间 的 Flux 来 实现 异步 转换 


下 面 的 测试 方法 展示 如 何 使 用 flatMap0 〇 方法 和 subscribeOn0 方 法 : 


QTest 
public void flatMap() { 
Flux<Player> playerFlux = Flux 
.just("Michael Jordan", "Scottie Pippen", "Steve Kerr") 
.flatMap(n -> Mono.just(n) 
.map(p -> { 
String[|] split = p.split("\\s"); 
return new Player(split[8], split[1]); 
}) 
.SubscribeOn(Schedulers.parallel()) 


)3 


List<Player> playerList = Arrays.asList( 
new Player("Michael", "Jordan"), 
new Player("Scottie", "Pippen"), 
new Player("Steve", "Kerr")); 


StepVerifier.create(playerFlux) 
.expectNextMatches(p -> playerList.contains(p) ) 
.expectNextMatches(p -> playerList.contains(p)) 
.expectNextMatches(p -> playerlList.contains(p)) 
.verifyComplete( ) ; 





需要 注意 的 是 ， 我 们 为 flatMap0 方 法 指定 了 一 个 lambda 形 式 的 也 
数 ， 传 入 的 String 将 会 转换 为 一 个 Mono 关 型 的 String， 然 后 在 这 个 Mono 
上 通过 map0) 方 法 将 字符 串 转 换 为 一 个 Player。 


如 条 到 此 为 止 ， 那 么 产生 的 Flux 将 同样 包含 Player 对 象 ， 与 使 用 
map() 方 法 的 例子 相同 ， 顺 序 同步 地 生成 。 但 是 我 们 对 Mono 做 的 最 后 一 
个 动作 就 是 调用 subscribeOn() 方 法 ， 它 声明 每 个 订阅 都 应 该 在 并 行 线程 
中 进行 ， 因 此 可 以 异步 并 行 地 执行 多 个 String 对 象 的 转换 操作 。 


你 管 subscribeOn() 方 法 的 命名 与 subscribe() 方 法 类 似 ， 但 是 它们 的 含 
义 却 完全 不 同 。 subscribe() 方 法 是 一 个 动词 ， 订 阅 并 驱动 反应 式 流 ; 而 
subscribeOn(0) 方 法 则 更 具 摘 述 性 ， 指 定 了 如 何 并 及 地 处 理 订 阅 。Reactor 
本 吴 并 不 强制 使 用 特定 的 并 发 模型 ， 通 过 subscribeOn(0) 方 法 ， 我 们 可 以 
使 用 Schedulers 中 的 任意 一 个 静态 方法 来 指定 并 友 模 型 。 在 这 个 例子 
中 ， 我 们 使 用 了 parallel0 方 法 ， 使 用 来 自 国 定 线 程 池 (大 小 与 CPU 核 心 
数量 相同 ) 的 工作 线程 。Schedulers 文 持 多 种 并 发 模型 ， 如 表 10.1 所 示 。 


表 10.1 Schedulers 支 持 的 并 发 模型 


Schedulers 、 
a 搬 述 
方法 

EN 





在 一 个 单一 的 、 可 重用 的 线程 中 执行 订阅 。 对 所 有 的 调用 者 重用 相同 
Single() 
的 线程 
针对 每 个 调用 ， 使 用 专用 的 线程 执行 订阅 


在 从 无 界 弹 性 线程 池 中 拉 取 的 工作 者 线程 中 执行 订阅 。 根据 需要 创建 





.elastic() 新 的 工作 线程 ， 并 销毁 空 亲 的 工作 者 线程 〈 默 认 情 况 下 ， 会 在 空 症 60 
秒 后 销毁 ) 


在 从 一 个 固定 大 小 的 线程 池 中 拉 取 的 工作 者 线程 中 执行 订阅 ， 该 线程 


.parallel() . 
池 的 大 小 和 CPU 的 核心 数 一 致 





使 用 flatMapO0 和 subscribeOnO 的 好 处 是 : 我 们 可 以 在 多 个 并 行 线程 
之 间 拆 分 工作 ， 从 而 增加 流 的 吞吐 量 。 因 为 工作 是 并 行 完成 的 ， 无 法 保 
证 哪 项 工作 首先 完成 ， 所 以 结果 Flux 中 数据 项 的 发 布 顺序 是 未 知 的 。 因 
此 ，StepVerifier 只 能 验证 发 出 的 每 个 数据 项 是 任 存 在 于 预期 Player 对 象 
列表 中 ， 并 且 在 Flux 完 成 之 前 会 有 3 个 这 样 的 数据 项 。 


在 反应 式 流 上 缓存 数据 


在 处 理 流 经 Flux 的 数据 时 ， 你 可 能 会 友 现 将 数据 流 拆 分 为 小 块 会 市 
来 一 定 的 收益 。 如 图 10.18 所 示 的 buffer 操 作 可 以 帮助 你 解决 这 个 问题 。 





buffer(maxSize=3) 


OO OO 





图 10.18 ”buffer 操 作 会 产生 一 个 新 的 包含 列表 Flux (具备 最 大 长 度 限制 的 列表 ， 
包含 从 传 入 的 Flux 中 收集 来 的 数据 ) 


我 们 给 定 一 个 包含 多 个 String 值 的 Flux， 其 中 每 个 值 代表 一 种 水 有 果 
的 名 称 ， 我 们 可 以 创建 一 个 新 的 包含 List 集合 的 Flux， 其 中 每 个 List 只 有 


不 超过 指定 数量 的 元 系 : 


QTest 
public void buffer() { 
Flux<String> fruitFlux = Flux.just( 
"apple", "orange", "banana", "kiwi", "strawberry"); 


Flux<List<String>> bufferedFlux = fruitFlux.buffer(3); 


StepVerifier 
.Create(bufferedFlux) 
.expectNext(Arrays.asList("apple", "orange", "banana")) 
.expectNext(Arrays.asList("kiwi", "strawberry")) 
.verifyComplete( ) ; 





在 这 种 情况 下 ，String 元 素 的 Flux 被 缓冲 到 一 个 新 的 包含 List 集 合 的 
Flux 中 ， 其 中 每 个 集合 不 超过 3 个 条 目 。 因 此 ， 有 发 出 5 个 String 信 的 原始 
Flux 将 会 被 转换 为 一 个 新 的 Flux， 它 会 发 出 两 个 List 集 合 ， 其 中 一 个 包 
含 3 个 水 果 ， 而 为 一 个 包含 2 个 水 果 。 


这 有 什么 意义 呢 ? 将 反应 式 的 Flux 绥 冲 到 非 反 应 式 的 Flux 中 看 起 来 
适得其反 ， 但 是 ， 当 组 合 使 用 buffer0 方 法 和 flatMap(0) 方 法 时 ， 我 们 可 以 
对 每 个 List 集 合 进行 并 行 处 理 。 

Flux.just( 
"apple", "orange", "banana", "kiwi", "strawberry") 


.buffer(3) 
.flatMap(x -> 


Flux.fromIterable(x) 
.map(y -> y.toUpperCase() ) 
.SubscribeOn(Schedulers.parallel()) 


.log() 
) .subscribel ) ; 





在 这 个 新 例子 中 ， 我 们 仍然 将 5 个 String 值 的 Flux 缓 冲 到 一 个 新 的 包 


舍 List 的 Flux 中 ， 但 是 这 次 将 flatMap0O 应 用 于 包含 List 集 合 的 Flux。 这 将 
医 取 每 个 List 绥 冲 区 ， 并 为 其 中 的 元 系 创 建 一 个 狐 的 Flux， 然 后 对 其 应 
用 map 操 作 。 因 此 ， 每 个 List 绥 种 区 都 会 在 各 个 线程 中 执行 进一步 并 行 
处 理 。 


为 了 观察 实际 的 效果 ， 在 代码 中 还 包括 了 一 个 log0) 操 作 ， 它 用 于 每 
个 子 Flux。 log0 操 作 记 录 了 所 有 的 反应 式 事件 ， 以 便于 观察 实际 发 生 了 
什么 事情 。 在 日 志 中 将 会 记录 如 下 的 条 目 〈 为 简洁 起 见 ， 删 除了 时 间 裁 
的 部 分 》: 


[main| INFO reactor.Flux.SubscribeOn.1 - 
onSubscribe(FluxSubscribeOn.SubscribeOnSubscriber) 

[main] INFO reactor.Flux.SubscribeOn.1 - request(32) 

[main| INFO reactor.Flux.SubscribeOn.2 - 
onSubscribe(FluxSubscribeOn.SubscribeOnSubscriber) 

[main] INFO reactor.Flux.SubscribeOn.2 - request(32) 


[parallel-1] INFO reactor.Flux.SubscribeOn.1 - onNext(APPLE) 
[parallel-2] INFO reactor.Flux.SubscribeOn.2 - onNext(KIWI) 


[parallel-1] INFO reactor.Flux.SubscribeOn.1 - onNext (ORANGE) 
[parallel-2] INFO reactor.Flux.SubscribeOn.2 - onNext(STRAWNBERRY ) 
[parallel-1] INFO reactor.Flux.SubscribeOn.1 - onNext(BANANA) 
[parallel-1] INFO reactor.Flux.SubscribeOn.1 - onCompletel() 
[parallel-2] INFO reactor.Flux.SubscribeOn.2 - onCompletel() 





如 同日 志 记 录 有 所 清晰 展示 的 ， 第 一 个 缕 冲 区 (apple、orange 和 
banana) 中 的 水 果 在 parallel-1 线 程 中 处 理 ， 与 此 同时 ， 第 二 个 组 证 区 
(kiwi 和 strawberry)〉 中 的 水 果 在 parallel-2 线程 中 处 理 。 从 缓冲 区 的 日 志 
记录 交织 在 一 起 的 事实 可 以 明显 地 看 出 ， 对 两 个 缓冲 区 的 处 理 是 并 行 执 
行 的 。 


如 由 由 于 菏 些 原因 高 要 将 Flux 友 布 的 所 有 数据 项 都 收集 到 一 个 List 


中 ， 那 么 可 以 使 用 不 市 参数 的 buffer0 方 法 : 


这 将 会 产生 一 个 新 的 Flux。 这 个 Flux 将 会 发 布 一 个 List， 其 中 包 售 
源 Flux 发 布 的 所 有 数据 项 。 我 们 可 以 使 用 collectList 操 作 实 现 相 同 的 功 
能 ， 如 图 10.19 中 的 弹 珠 图 所 示 。 





外 | 
OTD 


图 10.19 collectList 操 作 将 产生 一 个 包含 传 入 Flux 发 布 的 所 有 消息 的 Mono 


collectList0 方 法 会 产生 一 个 发 布 List 的 Mono， 而 不 是 发 布 List 的 
Flux。 下 面 的 测试 方法 展示 了 它 的 用 法 : 
QTest 
public void collectList() { 
Flux<String> fruitFlux = Flux.just( 


"apple",， “Orange ， “banana  ， "kiwi", "strawberry" ); 


Mono<List<String>> fruitListMono = fruitFlux.collectList(); 


StepVerifier 
.Create(fruitListMono) 
.expectNext(Arrays.asList( 
"apple", "orange", "banana", "kiwi", "strawberry")) 
.verifyComplete( ) ; 





一 种 更 加 有 趣 的 收集 Flux 友 出 的 数据 项 的 方法 是 将 它们 收集 到 Map 


中 。 如 图 10.20 有 所 示 ，collectMap 操作 将 会 产生 一 个 用 布 Map 的 Mono， 
这 个 Map 中 填充 了 由 给 定 Function 计 算 key 值 所 生成 的 条 目 。 


+ + 
collectMap( k( © )) 


图 10.20 ”collectMap 操 作 将 会 产生 一 个 Mono( 包 含 了 由 传 入 Flux 所 发 出 的 消 居 产生 的 Map， 这 
个 Map 的 key 是 从 传 入 消息 的 茶 些 特征 衍生 而 来 的 ) 











要 查看 collectMap() 的 效果 ， 请 参考 下 面 的 测试 方法 : 


QTest 
public void collectMap() { 
Flux<String> animalFlux = Flux.just( 
"aardvark", "elephant", "koala", "eagle", "kangaroo" ) ; 


Mono<Map<Character, String>> anijmalMapMono = 
animalFlux.collectMap(a -> a.charAt(0)); 


StepVerifier 


.Create(animalMapMono) 
.expectNextMatches(map -> { 
return 


map.size() == 3 && 
map.get('a').equals("aardvark") && 
map.get('e').equals("eagle") && 
map.get('k').equals("kangaroo" ); 
}) 
.verifyComplete( ) ; 





源 Flux 会 发 布 一 些 动 物 的 名 字 。 基 于 这 个 Flux， 我 们 使 用 collectMap 
操作 创建 了 一 个 发 布 Map 的 新 Mono， 其 中 key 由 动物 名 称 的 首 字母 确 


定 ， 而 值 则 为 动物 名 称 本 刁 。 如 果 两 个 动物 名 称 以 相同 的 字母 开头 
(如 elephant 和 eagle， 或 者 koala 和 kangaroo) ， 那 么 流 经 该 流 的 最 后 一 


个 条 目 将 会 覆盖 先前 的 条 目 。 
10.3.4 在 反应 式 类 型 上 执行 志和 辑 操作 


有 时 候 我 们 想 要 知道 由 Mono 或 者 Flux 发 布 的 条 有 目 是 人 否 满 足 某 些 条 
件 ， 那 么 al0 和 any0) 方 法 可 以 实现 这 样 的 馆 辑 。 图 10.21 和 图 10.22 展 示 
了 al0 和 any0O 的 工作 方式 。 


图 10.21 可 以 使 用 al0 方 法 来 确保 Flux 中 的 所 有 消息 都 满足 某 些 条 件 


| 
图 10.22 ”可 以 使 用 any0 方 法 来 确保 Flux 中 人 至少 有 一 个 消 居 满足 菜 些 条 件 


假设 我 们 想 知 道 Flux 发 布 的 每 个 String 中 是 任 剖 包含 了 字母 a 或 字母 


k， 那 么 下 面 的 测试 将 使 用 all0 方 法 来 检查 这 个 条 件 : 


QTest 
public void all() { 
Flux<String> animalFlux = Flux.just( 
"aardvark", "elephant", "koala", "eagle", "kangaroo" ) ; 


Mono<Boolean> hasAMono = animalFlux.all(a -> a.contains("a")); 
StepVerifier.create(hasAMono) 

.expectNext (true) 

.verifyComplete(); 


Mono<Boolean> hasKMono = animalFlux.all(a -> a.contains("k")); 
StepVerifier.create(hasKMono) 

.expectNext(false) 

.verifyComplete(); 





在 第 一 个 StepVerifier 中 ， 我 们 检查 了 字母 a8。all() 方 法 应 用 于 源 
Flux， 会 产生 布尔 类 型 的 Mono。 在 本 例 中 ， 所 有 动物 名 称 都 包含 了 了 字 
母 a， 所 以 从 生成 的 Mono 中 会 发 布 ttue。 但 是 在 第 二 个 StepVerifier 中 ， 
产生 的 Mono 将 会 及 出 false， 因 为 并 非 所 有 动物 名 称 都 包含 字母 k。 


如 果 人 至少 有 一 个 元 系 罗 配 条 件 即 可 ， 而 不 是 要 求 所 有 元 系 均 满足 条 
件 ， 那 么 any0 束 是 我 们 所 需 的 方法 。 下 面 这 个 新 的 测试 用 例 使 用 any0 
来 检查 字母 tflz: 





QTest 
public void any() { 
Flux<String> animalFlux = Flux.just( 
"aardvark", "elephant", "koala", "eagle", "kangaroo"); 


Mono<Boolean> hasAMono = animalFlux.any(a -> a.contains("t")); 


StepVerifier.create(hasAMono) 
.expectNext (true) 
.verifyComplete(); 


Mono<Boolean> hasZMono = animalFlux.any(a -> a.contains("z")); 
StepVerifier.create(hasZMono) 

.expectNext(false) 

.verifyComplete(); 





在 第 一 个 StepVerifier 中 ， 我 们 会 看 到 生成 的 Mono 友 布 了 true， 因 为 
至 少 有 一 种 动物 的 名 称 含有 字母 t〈 尤 其 是 elephant〉。 而 在 第 二 种 情况 
下 ， 生 成 的 Mono 发 布 了 false， 因 为 没有 任何 一 种 动物 的 名 称 包含 字母 


10.4 ”小结 


。 友 应 去 编程 会 涉及 创建 数据 沉 经 的 处 理 管道 。 

e。 反应 云 泊 规范 定义 了 4 种 类 型 : Publisher、Subscriber、Subscription 
和 Processor 〈 它 是 Publisher 和 Subscriber 的 组 合 ) 。 

。 Reactor 项 目 实现 了 反应 陈 沉 规范 ， 将 反应 陈 诉 的 定义 抽象 为 两 个 主 
要 的 类 型 ， 即 Flux 和 Mono， 并 为 每 种 类 型 都 提供 数 百 个 操作 。 

。 Spring 5 利用 Reactor 提 供 了 反应 式 控制 硕 、repository、REST 客 户 尊 
以 及 其 他 反应 式 框 染 的 支持 。 


第 11 章 ” 开 友 反应 式 API 


。 使 用 Spring WebFlux 


e。 编写 和 测试 反应 式 的 控制 需 以 及 客户 关 
。 消费 REST API 


。 你 护 反 应 式 Web 应 用 





我 们 已 经 了 解 了 反应 式 编 程 和 Reactor 项 目 ， 现 在 可 以 开始 在 Spring 
应 用 程序 中 使 用 这 些 技术 了 。 在 本 章 中 ， 我 们 将 利用 Spring 5 的 反应 式 
编程 模型 重新 讨论 在 第 6 章 中 编写 的 控制 共 。 


具体 来 讲 ， 我 们 将 一 起 探讨 Spring 5 中 新 添加 的 反应 式 Web 框 架 
Spring WebFlux。 我 们 很 快 会 发 现 ，Spring WebFlux 与 Spring MVC 
韭 党 相似 ， 这 样 使 得 它 非常 易于 使 用 ， 我 们 已 经 掌握 的 如 何在 Spring 中 
构建 REST API 的 知识 依然 有 用 。 





11.1 使 用 Spring WebFlux 


传统 的 基于 Servlet 昌 Web 框架， 如 Spring MVC， 在 本 质 上 都 是 阻 老 
和 多 线程 的 ， 每 个 连接 都 会 使 用 一 个 线程 。 在 请 求 处 理 的 时 候 ， 会 在 线 
程 池 中 拉 取 一 个 工作 者 (worker) 线程 来 对 请 求 进行 处 理 。 同 时 ， 请 求 
线程 是 阻 压 的 ， 直 到 工作 者 线程 提示 它 已 经 完成 为 止 。 


这 样 市 来 的 后 果 束 是 阻 窟 式 Web 框 架 在 大 量 请 求 下 无 法 有 效 地 扩 
展 。 绥 慢 的 工作 者 线程 所 市 来 的 延 运 会 使 情况 变 得 更 糟 ， 因 为 它 将 化 费 
更 长 的 时 间 才 能 将 工作 者 线程 送 回 池 中 ， 准 备 处 理 另 一 个 请 求 。 在 茶 些 
场景 中 ， 这 种 设计 完全 可 以 接受 。 事 实 上 ， 在 很 大 程度 上 这 就 是 十 多 年 
来 大 多 数 Web 应 用 程序 的 开 友 方式 ， 但 是 时 代 在 改变 。 


这 些 Web 应 用 程序 的 客户 端 以 前 是 偶尔 浏览 网 站 的 人 们 ， 而 现在 这 
些 人 会 频繁 消费 内 容 而 且 会 使 用 与 HTTP API 协 作 的 应 用 程序 。 如 今 ， 
物 联网 (甚至 不 需要 人 类 ) 产生 了 汽车 、 喷 气 式 发 动机 和 其 他 非 传统 的 
客户 端 ， 它 们 会 持续 地 和 Web API 交 换 数据 。 随 着 消费 Web 应 用 的 客户 
端 越 来 越 多 ， 可 扩展 性 比 以 往 任何 时 候 都 更 加 重要 。 


异步 的 Web 框 织 能 够 以 更 少 的 线程 获得 更 局 的 可 扩展 性 ， 通 第 它 们 
只 需要 与 CPU 核心 数量 相同 的 线程 。 通 过 使 用 所 谓 的 事件 轮 询 (event 
looping〉 机 制 《 如 图 11.1 所 示 〉， 这 些 框 染 能 够 用 一 个 线程 处 理 很 多 请 
求 ， 这 样 每 次 连接 的 成 本 会 更 低 。 


CPU core 


推送 请 求 事件 注册 回调 密集 型 操作 


事件 轮 询 


触发 回调 推送 操作 完成 事件 





图 11.1 弄 步 Web 框 腑 依 助 事件 轮 询 机 制 能 够 以 更 少 的 线程 处 理 更 多 的 请 求 


在 事件 轮 询 中 ， 所 有 事情 都 是 以 事件 的 方式 来 进行 处 理 的 ， 包 括 请 
求 以 及 密集 型 操作 《如 数据 库 和 网 络 操作 ) 的 回调 。 当 需要 执行 成 本 高 
局 的 操作 时 ， 事 件 轮 询 会 为 该 操作 注册 一 个 回调 ， 这 样 操 作 可 以 并 行 执 
行 ， 而 事件 轮 询 则 会 继续 处 理 其 他 的 事件 。 


当 操 作 完 成 时 ， 事 件 轮 询 机 制 会 将 其 作为 一 个 事件 ， 这 一 点 与 请 求 
是 相同 的 。 这 样 达到 的 效果 就 是 ， 在 面临 大 量 人 负载 的 时 候 ， 弄 步 Web 框 
淋 能 够 以 更 少 的 线程 实现 更 好 的 可 扩展 性 ， 这 样 会 减少 线程 官 理 的 开 
销 。 


Spring 5 引入 了 一 个 非 阻 宗 、 开 步 的 Web 框 如 ， 访 框 女 在 很 大 程度 
上 是 基于 Reactor 项 目的 ， 能 够 解决 Web 应 用 和 API 中 对 更 好 的 可 扩展 性 
的 需求 。 接 下 来 我 们 看 一 下 Spring WebFlux: 面 加 Spring 的 反应 式 Web 框 


昌 
淋 。 


11.1.1 Spring WebFlux 倍 介 


当 Spring 团 队 思 考 如 何 同 Web 层 深 加 反 应 式 编 程 模型 时 ， 如 有 果 不 在 
Spring MVC 中 做 大 量 工作 ， 显 然 很 难 实现 这 一 点 。 这 会 在 代码 中 产生 分 
文 以 决定 是 售 要 以 反应 式 的 方式 来 处 理 请 求 。 如 果 这 样 做 ， 本 质 上 吏 是 
将 两 个 web 框架 打 包 成 一 个 ， 依 靠 让 语句 来 区 分 反应 式 和 非 反 应 却 。 


与 其 将 反应 式 编 程 模 型 硬 塞 进 Spring MVC 中 ， 还 不 如 创建 一 个 单独 
的 反应 式 Web 框 架 ， 并 尽 可 能 多 地 借鉴 Spring MVC。 这 样 ，Spring 
WebFlux 就 应 运 而 生 了 。Spring 5 定义 的 完整 Web 开 发 技术 栈 如 图 11.2 所 


不 。 
LE- 
EE 
see 
Netty, Undertow 
图 11.2 ”Spring 5 通过 名 为 WebFlux 的 新 Web 框 架 来 支持 反应 式 Web 应 用 


在 图 11.2 的 左 侧 ， 我 们 会 看 到 Spring MVC 技 术 栈 ， 这 是 Spring 框架 
2.5 版 本 就 引入 的 。Spring MVC 〈 在 第 2 章 和 第 6 章 已 经 进行 了 讨论 ) 建 
在 Java Servlet API 之 上 上， 因此 需要 Servlet 容 硕 〈 比 如 Tomcat) 才能 执 


一 一 


位。 


与 之 不 同 ，Spring WebFlux 〈 在 图 11.2 的 右 侧 ， 和 Spring MVC 系 出 
同门 ， 并 且 很 多 核心 组 件 都 是 公用 的 ) 并 不 会 绑 定 Servlet API， 所 以 它 


构建 在 Reactive HTTP API 之 上 ， 这 个 API 与 Servlet API 具 有 相同 的 功 
能 ， 只 不 过 是 采用 了 反应 陈 的 方式 。 因 为 Spring WebFlux 疫 有 与 Servlet 
API 耦 合 ， 所 以 它 的 运行 并 不 需要 Servlet 容 器 。 它 可 以 运行 在 任意 非 阻 
塞 Web 容 器 中 ， 包 括 Netty、Undertow、Tomcat、Jetty 或 任意 Servlet 3.1 
及 以 上 的 容器 。 


在 图 11.2 中 ， 最 值得 注意 的 是 左上 角 ， 它 代表 了 Spring MVC 和 
Spring WebFlux 公 用 的 组 件 ， 主 要 用 来 定义 控制 右 的 注解 。 因 为 Spring 
MVC 和 Spring WebFlux 会 使 用 相同 的 注解 ， 所 以 Spring WebFlux 与 
Spring MVC 在 很 多 方面 并 没有 区 别 。 


右上 角 的 方 框 表 示 另 一 种 编程 模型 ， 它 使 用 图 数 式 编程 范式 来 定义 
控制 硕 ， 而 不 是 使 用 注解 。 在 11.2 贡 中 ， 我 们 将 更 多 地 讨论 Spring 的 函 
数 式 Web 编 程 模型 。 


Spring MVC 和 Spring WebFlux 之 则 最 显 阁 的 区 列 在 于 ， 我 们 要 将 哪 
个 依赖 项 请 加 到 构建 文件 中 。 在 使 用 Spring WebFlux 时 ， 我 们 需要 湛 加 
Spring Boot WebFlux starter 依 顿 项 ， 而 不 是 标准 的 Web starter 〈 例 如 ， 
spring-boot-starter-web) 。 在 项 目的 pom.xml 文 件 中 ， 如 下 所 示 : 
<dependencyy 
<groupId>org. springframework.boot</groupId> 


<artifactId>spring-boot-starter-webflux</artifactId> 
</dependency> 


注意 : 与 Spring Boot 的 大 多 数 starter 依 赖 类 似 ， 这 个 starter 也 
可 以 在 Initializr 中 通过 选中 Reactive Web 复 选 框 添加 到 项 目 中 。 





Oy 


使 用 WebFlux 有 一 个 很 有 意思 的 副作用 ， 即 WebFlux 的 默认 通 入 式 
服务 器 是 Netty 而 不 是 Tomcat。Netty 是 一 个 异步 、 事 件 驱 动 的 服务 器 ， 


非常 适合 Spring WebFlux 这 样 的 反应 式 Web 框 架 。 


除了 使 用 不 同 的 starter 依 赖 之 外 ，Spring WebFlux 的 控制 器 方法 要 接 
受 和 返回 反应 式 类 型 ， 如 Mono 和 Flux， 而 不 是 领域 类 型 和 集合 。Spring 
WebFlux 控 制 器 也 能 处 理 RxJava 类 型 ， 如 Observable、Single 和 
Completable。 


反应 式 Spring MVC 


尽管 Spring WebFlux 控 制 似 通 第 会 返回 Mono 和 Flux， 但 是 这 并 不 意 
味 着 Spring MVC 无 法 体验 反应 式 类 型 的 乐趣 。 如 果 你 原意， 那么 Spring 
MVC 也 可 以 返回 Mono 和 和 Flux。 


这 里 的 区 列 在 于 ， 这 些 闫 型 会 如 何 被 使 用 。Spring WebFlux 是 真正 
的 反应 式 Web 框 架 ， 人 允许 在 事件 轮 询 中 处 理 请 求 ， 而 Spring MVC 征 基于 
ServletHj， 依 赖 于 多 线程 来 处 理 多 个 请 求 。 


接 下 来 ， 我 们 让 Spring WebFlux 运 行 起 来 ， 借 助 Spring WebFlux 重 
新 编写 Taco Cloud 的 API 控 制 器 。 


11.1.2 ” 编 与 反应 陈 探 制 需 


你 可 能 还 记得 在 第 6 章 中 我 们 为 Taco Cloud 的 REST API 创 建 了 一 些 
控制 右 ， 这 些 控制 器 中 包含 请 求 处 理 方 法 ， 这 些 方法 会 以 领域 类 型 〈 如 
Order 和 Taco) 或 领域 类 型 集合 的 方式 处 理 输 入 和 输出 。 作 为 所 醒 ， 我 
们 看 一 下 在 第 6 章 所 编号 的 DesignTacoController 片 段 : 

QRestController 
@QRequestMapping(path="/design",， 
produces="application/json") 


QCrossOrigin(origins="*") 
public class DesignTacoController { 


@GetMapping("/recent") 


public Iterable<Taco> recentTacos() { 
PageRequest page = PageRequest.of( 
80, 12, Sort.by("createdAt").descending()); 
return tacoRepo.findAll(page).getContent(); 
} 





按照 以 上 的 编写 形式 ，recentTacos() 控 制 右 会 处 理 
对 “design/recent" 的 HITP GET 请求， 返回 最 近 创 建 的 taco 列 表 。 其 体 来 
讲 ， 它 会 返回 Taco 类 型 的 Iterable。 这 主要 是 因为 repository 的 findA]1(0) 方 
法 返回 的 束 是 该 类 型 ， 或 者 更 准确 地 说 ， 这 个 结果 来 自 findAll0 方 法 所 
返回 的 Page 对 象 的 getContentO 方 法 。 


这 样 能 够 很 好 地 运行 ， 但 是 Iterable 并 不 是 反应 式 类 型 。 我 们 不 能 对 
它 使 用 任何 反应 式 操作 ， 也 不 能 让 框架 将 它 视 为 反应 陈 类 型 ， 从 而 将 工 
作 切 分 到 多 个 线程 中 。 我 们 和 希望 recentTacos(0) 方 法 能 够 返回 


Flux<Taco>。 


这 里 有 一 个 简单 但 效果 有 限 的 方案 : 重 写 recentTacos()， 将 Iterable 
转换 为 Flux。 而 且 ， 在 重 写 的 时 候 ， 我 们 可 以 去 挥 分 页 代码 ， 将 其 蔡 换 
为 调用 Flux 的 take0): 


@QGetMapping("/recent") 
public Flux<Taco> recentTacos() { 


return Flux.fromIterable(tacoRepo.findAll()).take(12); 
} 





借助 Flux.fromIterable()， 我 们 可 以 将 Iterable<Taco> 转 换 为 
Flux<Taco>。 既 然 我 们 可 以 使 用 Flux 了 ， 那 么 束 能 使 用 take 操 作 将 Flux 
返回 的 值 限制 为 最 多 12 个 Taco 对 象 。 不 仪 代码 更 加 简洁， 而 且 我 们 能 够 
处 理 反 应 式 的 Flux， 而 不 是 简单 的 Iterable。 


到 目前 为 止 ， 我们 编写 反应 式 代 人 码 一 切 都 很 顺利 。 如 果 repository 一 
开始 就 给 我 们 一 个 Flux 那 就 更 好 了 ， 束 没有 必要 进行 转换 了。 如 果 能 够 
实现 这 一 点 ， 那 么 recentTacos() 将 会 写成 如 下 形式 : 


@QGetMapping("/recent") 
public Flux<Taco> recentTacos() { 


return tacoRepo.findAll() .take(12); 
} 





这 样 就 更 好 了 ! 在 理想 情况 下 ， 肥 应 式 控 制 硕 将 会 位 于 反应 式 闹 到 
端 栈 的 顶部 ， 这 个 栈 包 括 了 控制 器 、repository、 数 据 库 以 及 在 它们 之 间 
可 能 还 会 包 合 的 服 务 。 这 样 的 闹 到 并 反应 式 栈 如 图 11.3 所 示 。 







请 求 /响应 


Flux/Mono 





数据 库 


图 11.3” 它 应 该 成 为 完整 的 端 到 痢 反 应 式 栈 的 一 部 分 (为 了 最 大 化 反应 式 Web 框 染 的 收 荔 ) 


这 样 的 端 到 端 技术 栈 要 求 repository 返 回 Flux， 而 不 是 Iterable。 在 第 
12 划 中 ， 我 们 将 会 详细 研究 如 何 编写 反应 式 repository， 但 是 反应 式 
TacoRepository 大 致 会 如 下 所 示 : 


public Interface TacoRepository 
extends ReactiveCrudRepository<Taco, Long> { 


} 


此 时 ， 了 最 需要 注意 的 事情 在 于 除了 使 用 Flux 来 普 换 Iterable 以 及 如 何 
获取 Flux 之 外 ， 定 义 反 应 式 WebFlux 控 制 占 的 编程 模型 与 非 反 应 式 
Spring MVC 控 制 旧 并 没有 什么 到 寞 。 它 们 痢 使 用 了 @RestController 注 解 
并 且 都 在 类 级 别 使 用 了 @RequestMapping。 它 们 都 有 在 方法 级 别 使 用 
@GetMapping 注 解 的 请 求 处 理 函 数 。 真 正 重要 的 是 处 理 需 方法 返回 了 什 


么 类 型 。 


男 外 值得 注意 的 是 ， 尺 官 我 们 从 repository 得 到 了 Flux<Taco>， 但 是 


我 们 直接 将 它 返回 了 ， 并 没有 调用 subscribe0。 框 架 将 会 为 我 们 调用 
subscribe()。 这 意味 着 当 处 理 “/design/recent” 请 求 的 时 候 ，recentTacos() 
方法 会 航 调用 ， 在 数据 真正 从 数据 库 取 出 之 前 它 就 能 立即 返回 。 


返回 单个 值 


作为 另外 一 个 样 例 ， 我 们 思考 一 下 在 第 6 草 中 编 与 的 
DesignTacoController 的 tacoByIdO) 方 法 : 


@GetMapping("/{id}") 

public Taco tacoById(@PathVariable("id") Long id) { 
Optional<Taco> optTaco = tacoRepo.findById(id); 
if (optTaco.isPresent()) { 


return optTaco.get() ; 


return null; 





} 


在 这 里 ， 该 方法 处 理 对 “/design/{id}” 的 GET 请 求 并 返回 单个 Taco 对 
象 。 因 为 repository 的 findById0O 返 回 的 是 Optional， 所 以 我 们 必须 编写 一 
些 烦琐 的 代码 处 理 它 。 如 果 findByIdO0 返 回 的 是 Mono<Taco>， 而 不 是 
Optional<Taco>， 那 么 我 们 可 以 按照 如 下 的 方式 重 写 控制 硕 的 
tacoByld( ): 


@GetMapping("/{id}") 
public Mono<Taco> tacoById(@PathVariable("id") Long id) { 


return tacoRepo.findById(id); 
} 





这 样 看 上 去 简单 多 了 。 更 重要 的 是 ， 通 过 返回 Mono<Taco> 来 蔡 代 
Taco， 我 们 能 够 让 Spring WebFlux 以 反应 式 的 方式 处 理 啊 应 。 这 样 做 的 


结果 就 是 在 面临 高 负载 的 时 候 我 们 的 API 能 够 更 好 地 进行 扩展 。 
使 用 RxJava 类 型 


值得 一 提 的 是 ， 在 使 用 Spring WebFlux 时 ， 虽 然 Flux 和 Mono 是 目 然 
而 然 的 选择 ， 但 是 我 们 也 可 以 使 用 像 Observable 和 Single 这 样 的 RxJava 类 
型 。 例 如 ， 假 设 在 DesignTacoController 和 后 端 repository 之 间 有 一 个 服 
务 ， 处 理 的 是 RxJava 类 型 ， 那 么 recentTacos() 方 法 可 以 编写 为 : 


@QGetMapping("/recent") 
public Observable<Taco> recentTacos() { 


return tacoService.getRecentTacos(); 


} 





类 似 的 ，tacoById0) 方 法 可 以 编写 成 处 理 RxJava Single 类 型 ， 而 不 是 


Mono 关 型 


@QGetMapping("/{id}") 
public Single<Taco> tacoById(@PathVariable("id") Long id) { 


return tacoService.lookupTaco(id); 


} 





除 此 之 外 ，Spring WebFlux 控 制 右 方法 还 可 以 返回 RxJava 的 
Completable， 后 者 等 价 于 Reactor 中 的 Mono<Void>。WebFlux 也 可 以 返 
回 Flowable， 符 换 Observable 或 Reactor 的 Flux。 


实现 输入 的 反应 式 


到 目前 为 止 ， 我 们 只 天 心 了 控制 此 方 法 返回 什么 样 的 反应 式 类 型 。 
但 是 ， 便 助 Spring WebFlux， 我 们 还 可 以 接受 Mono 或 Flux 作 为 处 理 右 方 


法 的 输入 。 为 了 兰 述 点 ， 请 思考 DesignTacoController 中 原始 的 
postTaco0 实 现 : 


@QPostMapping(consumes="application/json") 
@ResponseStatus(HttpStatus .CREATED) 


public Taco postTaco(@RequestBody Taco taco) { 
return tacoRepo.save(taco); 


} 





按照 原始 的 编写 方式 ，postTaco0) 不 仅 会 返回 一 个 徐 单 的 Taco 对 
象 ， 还 会 接受 一 个 Taco， 这 个 对 象 绑 定 了 请 ps 的 内 容 。 这 意味 看 在 
请 求 载荷 完成 解析 并 初始 化 为 Taco 对 象 之 前 ，postTaco0 方 法 是 不 会 被 
调用 的 。 这 同时 也 意味 着 ， 在 对 repository 的 save() 方 法 的 阻塞 调用 返回 
之 前 ，postTaco0 征 不 能 返回 的 。 人 徐 而 言 之 ， 本 了 两 次 ; 在 
进入 postTaco0 的 时 候 以 及 在 postTaco0) 调 用 的 过 程 中 。 通 过 为 postTaco0) 
浦 加 一 些 反 应 云 代 码 ， 我 们 能 够 将 它 变 成 完全 非 阻 塞 的 请 ed 


@PostMapping(consumes="application/json") 
@ResponseStatus(HttpStatus .CREATED) 


public Mono<Taco> postTaco(@RequestBody Mono<Taco> tacoMono) { 
return tacoRepo.saveAll(tacoMono).next(); 


} 





在 这 里 ，postTaco() 接 受 一 个 Mono<Taco> 并 调用 了 repository 的 
saveAll() 方 法 。 我 们 将 会 在 第 12 章 看 到 这 个 repository 能 够 接受 反应 式 沉 
Publisher 的 任意 实现 ， 包 括 Mono 或 Flux。saveAl10 方 法 返回 了 一 个 
Flux<Taco>， 但 我 们 想 要 的 是 Mono。 我 们 知道 该 Flux 最 多 只 能 发 布 一 个 
Taco， 所 以 调用 next() 方 法 获取 postTaco0 方 法 要 返回 的 Mono<Taco>。 


通过 接受 Mono<Taco> 作 为 输入 ， 方 法 会 立即 调用 ， 不 用 等 待 从 请 


求 体 中 解析 生成 Taco。 男 外 ，repository 也 是 反应 式 的 ， 它 接受 一 个 
Mono 并 立即 返回 Flux<Taco>， 上 所 以 我 们 调用 Flux 的 next() 来 获取 最 终 的 
Mono<Taco>。 方 法 在 请 求 真 正人 处 理 之 前 束 能 返回 


Spring WebFlux 是 一 个 非常 棒 的 Spring MVC 蔡 代 方案 ， 提供 了 与 
Spring MVC 相 同 的 开发 模型 来 编号 反应 式 Web 应 用 。 其 实 Spring 5 还 有 
万 外 一 项 拉 巧 ， 下 面 让 我 们 看 看 如 何 使 用 Spring 5 的 新 函 效 式 编程 风格 
创建 反应 式 APT。 


11.2 定义 疯 数 式 请 求 处 理 桥 


Spring MVC 基 于 注解 的 编程 模型 从 Spring 2.5 束 存在 了 ， 而 且 这 种 
模型 非常 流行 ， 但 是 它 也 有 一 些 缺 点 。 


首先 ， 所 有 基于 注解 的 编程 方式 都 会 存在 注解 该 做 什么 以 及 注解 如 
何 做 之 间 的 制 勿 。 注 解 本 里 定义 了 该 做 什么 ， 而 其 体 如 何 去 做 则 是 在 框 
染 代 人 码 的 其 他 部 分 定义 的 。 如 果 想 要 进行 目 定义 或 扩展 ， A 
变 得 很 复杂 ， 因 为 这 样 的 变更 需要 修改 注解 乙 外 的 代码 。 除 此 之 外 ， 
种 代码 的 调试 也 是 比较 麻烦 的 ， 因 为 我 们 无 法 和 在 注解 上 设置 断 点 。 


其 次 ， 随 独 Spring 变 得 越 来 越 沉 行 ， 很 多 见 芒 其 他 语言 和 框架 的 
Spring 新 手 会 党 得 基于 注解 的 Spring MVC (和 WebFlux) 与 他 们 之 前 等 
握 的 知识 有 很 大 的 差异 。 作 为 注解 式 WebFlux 的 一 种 蔡 代 方案 ，Spring 5 
引入 了 一 个 新 的 函数 却 编 程 模型 ， 用 来 定义 反应 式 API。 


这 个 新 的 编程 模型 使 用 起 来 更 像 一 个 库 ， 而 不 是 一 个 框架 ， 能 够 让 


我 们 在 不 使 用 注解 的 情况 下 将 请 求 映 射 到 处 理 器 代码 中 。 使 用 Spring 的 
函数 式 编 程 模型 编写 API 会 涉及 4 个 主要 的 类 型 ; 


。 RequestPredicate: 声明 要 处 理 的 请 求 交 型。 

。 RouterFunction: 声明 如 何 将 请 求 路 由 到 处 理 带 代码 中 。 

。 ServerRequest: 代表 一 个 HTTP 请 求 ， 包 括 对 请 求 头 和 请 求 体 的 访 
问 。 

。 ServerResponse: 代表 一 个 HITP 啊 应 ， 包 括 啊 应 头 和 啊 应 体 信息 。 


下 面 古 一 个 将 所 有 类 型 组 合 在 一 起 的 Hello World 样 例 : 


package demo ; 


import 
import 
import 
import 
import 


import 
import 


@Configuration 
public class RouterFunctionConfig { 


QBean 


static 


static 


static 


static 


org.springframework .web. 
reactive.function.server.RequestPpredicates .GET; 
org.springframework .web. 
reactive.function.server.RouterFunctions.route; 
org.springframework .web. 
reactive.function.server.ServerResponse.ok; 
reactor.core.publisher.Mono.jJust; 


org.springframework.context.annotation.Bean; 
org.springframework.context.annotation.Configuration; 
org.springframework .web.reactive.function.server.RouterFunction,; 


public RouterFunction<?> helloRouterFunction() { 
return route(GET("/hello"), 
request -> ok().body(just("Hello World!"), String.class)); 





我 们 需要 注意 的 第 一 件 事情 束 是 ， 在 这 里 静态 寻 入 了 一 些 辅助 类 ， 


可 以 使 用 它们 来 创建 前 文 所 述 的 函数 式 类 型 。 


我 们 还 以 静态 方式 导入 了 


Mono， 从 而 能 够 让 剩余 的 代码 更 易于 阅读 和 理解 。 


在 这 个 @Configuration 类 中 ， 我 们 有 一 个 类 型 为 RouterFunction<?> 
的 @Bean 方 法 。 按 照 前 文 所 述 ，RouterFunction 能 够 声明 一 个 或 多 个 
RequestPredicate 对 象 和 处 理 与 之 匹配 的 请 求 的 函数 之 间 的 映射 天 系 。 


RouterFunctions 的 route() 方 法 接受 两 个 参数 : RequestPredicate 以 及 
处 理 与 之 匹配 的 请 求 的 函数 。 在 本 例 中 ，RequestPredicates 的 GETO 方 法 
声明 一 个 RequestPredicate， 后 者 会 匹配 针对 “hello” 的 HTTP GET 请 求 。 


至 于 处 理 器 函数 ， 它 写成 了 lambda 表 达 式 的 形式 ， 当 然 它 也 可 以 使 
用 方法 引用 。 尽 管 这 里 没有 显 陈 声明 ， 但 是 处 理 卉 lambda 表 这 陈 会 接受 
一 个 ServerRequest 作 为 参数 。 它 通过 ServerResponse 的 okO) 方 法 和 
BodyBuilder 的 podyO 方 法 返回 了 一 个 ServerResponse。BodyBuilder 对 和 象 
征 由 ok0O 所 返回 的 。 这 样 的 话 ， 融 会 创建 出 状态 但 为 HITP 200 (OK) 并 
且 啊 应 体 载 傈 为 “Hello World!” 的 啊 应 。 


按照 这 种 编写 形式 ，helloRouterFunction() 方 法 所 声明 的 
RouterFunction 只 能 处 理 一 种 类 型 的 请 求 。 如 果 想 要 处 理 不 同类 型 的 请 
求 ， 那 么 我 们 没有 必要 编写 为 外 一 个 @Bean 当然 你 也 可 以 这 样 做 〉， 
仅 需 调用 andRoute0 来 声明 另 一 个 RequestPredicate 到 函数 的 映射 。 例 
如 ， 为 “/bye” 的 GET 请 求 添加 一 个 处 理 器 : 





QBean 
public RouterFunction<?> helloRouterFunction() { 
return route(GET("/hello"), 
request -> ok().body(just("Hello World!"), String.class)) 
.andRoute(GET("/bye"), 
request -> ok().body(just("See yal!"), String.class)); 


DJ 


Hello World 这 种 级 别 的 样 例 只 能 用 来 答 单 体验 一 些 新 东西 。 接 下 
来 ， 我 们 进一步 看 一 下 如 何 使 用 Spring 的 函数 式 wWeb 编 程 模型 处 理 接 近 
真实 场景 的 请 求 。 


为 了 曾 述 如 何在 真实 应 用 中 使 用 函数 陈 编程 模型 ， 我 们 会 使 用 函数 
式 风格 重新 实现 DesignTacoController 的 功能 。 如 下 的 配置 类 是 
DesignTacoController 的 函数 式 实现 : 


@Configuration 
public class RouterFunctionConfig { 


QAutowired 
private TacoRepository tacoRepo; 


QBean 
public RouterFunction<?> routerFunction() { 
return route(GET("/design/taco"), this::recents) 
.andRoute(POST("/design"), this::postTaco); 
} 


public Mono<ServerResponse> recents(ServerRequest request) { 
return ServerResponse.ok() 
.body(tacoRepo.findAll().take(12), Taco.class); 
} 


public Mono<ServerResponse> postTaco(ServerRequest request) { 
Mono<Taco> taco = request.bodyToMono(Taco.class); 
Mono<Taco> savedTaco = tacoRepo.savel(taco); 
return ServerResponse 
.Created(URI.create(l 
"http://localhost:80686/design/taco/" + 
savedTaco.getId())) 
.body(savedTaco, Taco.class); 





我 们 可 以 看 到 ，routerFunction() 方 法 声明 了 一 个 RouterFunction<?> 


bean， 这 与 Hello World 样 例 奖 似 。 但 是 ， 它 们 之 间 的 甜 异 在 于 要 处 理 什 
么 类 型 的 请 求 以 及 如 何 处 理 。 在 本 例 中 ， 我 们 创建 的 RouterFunction 处 
理 针 对 “design/taco” 的 GET 请 求 以 及 针对 “design” 的 POST 请 求 。 


更 明显 的 差 寞 在 于 ， 路 由 是 由 方法 引用 处 理 的 。 如 果 
RouterFunction 背 后 的 行为 相对 简单 和 人 简洁， 那么 lambda 是 很 不 错 的 选 
择 。 在 很 多 场景 下 ， 最 好 将 功能 抽取 到 一 个 单独 的 方法 中 (甚至 抽取 到 
一 个 独立 类 的 方法 中 ) ， 以 便于 保持 代码 的 可 读 性 。 


就 我 们 的 需求 而 言 ， 针 对 “/design/taco” 的 GET 请 求 将 由 recents() 方 法 
来 处 理 。 它 使 用 注入 的 TacoRepository 得 到 一 个 Flux<Taco>， 然 后 从 中 
得 到 12 个 条 目 。 针 对 “/design” 的 POST 请 求 会 由 postTaco0 方 法 来 处 理 ， 
它 会 从 传 入 的 ServerRequest 中 抽取 Mono<Taco>。postTaco() 使 用 
TacoRepository 方 法 来 进行 保存 ， 随 后 使 用 save0O) 人 返回 的 Mono<Taco> 作 
为 啊 应 。 


11.3 ”测试 反应 式 控 制 疾 


在 反应 式 控 制 桥 的 测试 方面 ，Spring 5 并 没有 置 我 们 于 不 兢 。 实 际 
上 ，Spring 5 引入 了 WebTestClient。 这 是 一 个 新 的 测试 工具 关 ， 让 Spring 
WebFlux 编 写 的 反应 式 控 制 磺 的 测试 变 得 非 芝 容 吻 。 为 了 了 解 如 何 使 用 
WebTestClient 编 瑟 测 试 ， 我 们 自 先 使 用 它 测 试 11.1.2 小 市 中 编写 的 
DesignTacoController 中 的 recentTacos() 方 法 。 


11.3.1 测试 GET 请 求 


对 于 recentTacos(0) 方 读 ， 我 们 想 断 言 如 采 针 对 “design/recent” 路 径 有 有 
送 HTTP GET 请 求 ， 那 么 将 会 得 到 JSON 载 荷 的 响应 并 且 taco 的 数量 不 会 
超过 12 个 。 程 序 清 单 11.1 中 的 测试 闫 将 会 是 一 个 很 好 的 起 点 。 


程序 清单 11.1 使 用 WebTestClient 测 试 DesignTacoController 


package tacos; 


import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 


public 


QTest 


static org.mockito.Mockito.*,; 
Java.util.ArrayList; 
Java.util.List,; 

org.Junit.Test; 
org.mockito.Mockito,; 
org.springframework.http.MediaType; 
org.springframework.test.web.reactive.server.WebTestClient; 
reactor.core.publisher.Flux; 
tacos.Ingredient.Type; 
tacos.data.TacoRepository; 

tacos .web.api.DesignTacoController; 


class DesignTacoControllerTest 1{ 


public void shouldReturnRecentTacos() { 
Taco[|] tacos = { 


Flux<Taco> tacoFlux = 


testTaco(1L), 
testTaco(3L), 
testTaco(5L), 


testTaco(2L )， 
testTaco(4L), 
testTaco(6L), 
testTaco(7L), testTaco(8L), 
testTaco(9L), testTaco(18L), 
testTaco(11L), testTaco(12L), 
testTaco(13L), testTaco(14L), 
testTaco(15L), testTaco(16L )}; 
Flux.just(tacos); 


一 --- 创建 测试 数据 


TacoRepository tacoRepo = Mockito.mock(TacoRepository.class); 


when(tacoRepo.findAll()).thenReturn(tacoFlux); 


全 --- Mock Taco 


Repository 


WebTestClient testClient = WebTestClient.bindToController( 


new DesignTacoController(tacoRepo)) 


.build(); 一 --- 创建 WebTestClient 


testClient.get().uri("/design/recent") 


.exchange() 一 --- 请 求 最 近 的 taco 
.expectStatus() .isok() 一 --- 检验 预期 的 啊 应 
.eXpectBody() 


.jsonpath("$").isArray() 

.jsonpath("$").isNotEmpty() 
.jsonPpath("$[60].id").isEqualTo(tacos[6]|].getId().toString()) 
.jsonPpath("$[6] .name").isEqualTo("Taco 1").jsonpath("$[1].id") 
.ijsEqualTo(tacos[1].getId().toString()).jsonpath("$[1].name") 
.ijsEqualTo("Taco 2").jsonpath("$[11].id") 
.isEqualTo(tacos[11|].getId().toString()) 


.jsonpath("$[11].name").isEqualTo("Taco 12").jsonpath("$[12]") 
.doesNotExist(); 
.jsonpath("$[12]").doesNotExist(); 


shouldReturnRecentTacos() 方 法 做 的 第 一 件 事情 束 是 以 Flux<Taco> 的 
形式 创建 了 一 些 测试 数据 。 这 个 Flux 随 后 作为 mock TacoRepository 的 
findAll() 方 法 的 返回 值 。 


Flux 发 布 的 Taco 对 象 是 由 一 个 名 为 testTaco0 的 方法 创建 的 。 这 个 方 
法 会 根据 一 个 数字 生成 一 个 Taco， 其 ID 和 名 称 都 是 基于 该 数字 生成 的 。 
testTaco() 方 法 的 实现 如 下 所 示 : 





private Taco testTaco(Long number) { 
Taco taco = new Taco() ; 
taco.setId(UUID.randomUUID( ) ) ; 
taco.setName("Taco ”+ number ) ; 
List<IngredientUDT> ingredients = new ArrayList<>() ; 
ingredients.add( 
new IngredientUDT("INGA", "Ingredient A", Type.WRAP)); 
ingredients.add( 
new IngredientUDT("INGB", "Ingredient B", Type.PROTEIN)); 
taco.setIngredients(ingredients ) ; 
return 七 aco ; 


| } | 


简 时 起见， 所 有 的 测试 taco 部 具有 两 种 相同 的 配料 ， 但 是 它们 的 ID 
和 名 称 古 根据 传 入 的 数字 确定 的 。 


另外 ， 回 到 shouldReturnRecentTacos() 方 法 ， 我 们 实例 化 了 一 个 
DesignTacoController 并 将 mock TacoRepository 注 入 到 了 构造 磊 中 。 这 个 
控制 右 传 递 给 了 WebTestCjlient. bindToController0 方 法 ， 以 便于 生成 
WebTestClient 实 例 。 


所 有 的 环境 搭建 工作 完成 后 ， 我 们 可 以 使 用 WebTestClient 提 交 GET 
请 求全 “/design/recent” 并 校 验 啊 应 符合 我 们 的 预期 。 对 
get().uri("/design/recent") 的 调用 摘 述 了 我 们 想 要 发 运 的 请 求 。 随 后 ， 调 
用 exchange0 会 提 区 请 求 ， 这 个 请 求 将 会 由 WebTestClient 绑 定 的 控制 需 


(DesignTacoController) 来 进行 处 理 。 


最 后 ， 我 们 可 以 确认 啊 应 符合 预期 。 通 过 调用 expectStatus()， 我 们 
可 以 断言 啊 应 具有 HTTP 200 (OK) 状 态 码 。 然 后 ， 我 们 多 次 调用 
jsonPathO 上 断言 啊 应 体 中 的 JSON 包 含 它 应 该 具有 的 仁 。 最 后 一 个 断言 检 
租 第 12 个 元 系 《〈 在 基于 零 开 始 计数 的 数组 中 ) 是 耕 真 的 不 存在 ， 以 此 判 
断 结果 不 超过 12 个 元 素 。 


如 采 返 回 的 JSON 比 较 复 洒 ， 比 如 有 大 量 的 数据 或 多 层 舱 父 的 数 
据 ， 那 么 使 用 jsonPathO 会 变 得 非常 烦琐 。 实 际 上 ， 为 了 和 省 空间 ， 在 程 
序 清单 11.1 中 ， 我 省 略 了 很 多 对 jsonPathO0) 的 调用 。 在 这 种 情况 下 ， 使 用 
jsonPathO 会 变 得 非常 枯燥 烦琐 ，WebTestClient 提 供 了 json0 方 法 。 这 个 


方法 可 以 传 入 一 个 String 参 数 (包含 啊 应 要 对 比 的 JSON) 。 


举例 来 说 ， 假 设 我 们 在 名 为 recent-tacos.json 的 文件 中 创建 了 完整 的 
响应 JSON 并 将 它 放 到 了 类 路 径 的 “tacos” 路 径 下 ， 那 么 我 们 可 以 按照 如 
下 的 方式 重 写 WebTestClient 汤 言 : 
ClassPathResource recentsResource = 
new ClassPathResource("/tacos/recent-tacos.json"); 


String recentsJson = StreamUtils.copyToString( 
recentsResource.getInputStream(), Charset.defaultCharset()); 


testClient.get().uri("/design/recent") 
.accept(MediaType.APPLICATION JSON) 
.exchange() 
.expectStatus().isOk() 
.expectBody() 
.json(recentsjJson); 





为 json0) 接 受 的 是 一 个 String， 所 以 我 们 必须 先 将 类 路 竹 资 源 加 载 
为 String。 借 助 Spring 中 StreamUtils 抱 copyToString0) 方 法 ， 这 一 点 很 容易 
实现 。copyToString(0) 方 法 返回 的 String 束 是 我 们 的 请 求 所 预期 的 啊 应 
JSON 内 容 。 将 其 传递 给 json0) 方 法 ， 我 们 就 能 确保 控制 右 会 生成 正确 的 
输出 。 


WebTestClient 提 供 的 为 外 一 种 可 选 方 案 束 是 它 允 许 将 啊 应 体 与 一 个 
值 的 列表 进行 对 比 。expectBodyListO) 方 法 会 接受 一 个 代表 列表 中 元 素 类 
型 的 Class 或 ParameterizedTypeReference， 并 且 会 返回 ListBodySpec 对 
象 ， 随 后 可 以 基于 该 对 象 进 行 断 言 。 借 助 expectBodyList()， 我 们 可 以 重 
写 测 试 类 ， 使 用 创建 mock TacoRepository 时 的 测试 数据 的 子 集 来 进行 验 
证 : 


testClient.get().uri("/design/recent") 
.accept(MediaType.APPLICATION JSON) 
.exchange() 


.expectStatus().isOk() 
.expectBodyList(Taco.class) 
.Contains(Arrays.copyof (tacos, 12)); 





在 这 里 ， 我 们 断言 啊 应 体 包 含 了 在 测试 方法 开 尖 处 所 创建 的 原始 
Taco 数 组 的 前 12 个 元 系 。 


11.3.2 ”测试 POST 请 求 
WebTestClient 不 仪 能 对 控制 占 发 送 GET 请 求 ， 还 能 用 来 测试 各 种 


HTTP 方 法 ， 包 括 GET、POST、PUT、PATCH、DELETE 和 HEAD 方 
法 。 表 11.1 将 HTTP 方 法 与 WebTestClient 的 方法 进行 了 映射 。 


表 11.1 WebTestCjlient 能 够 测试 针对 Spring WebFlux 控 制 器 的 各 种 请 求 


HTTP 方 法 WebTestClient 方 法 


PATCH .patch() 





DELETE .delete() 





作为 测试 Spring WebFlux 控 制 右 其 他 HTTP 请 求 方法 的 样 例 ， 我 们 看 
一 下 针对 DesignTacoController 的 另 一 个 测试 。 这 一 次 ， 我 们 会 编写 一 1 
对 taco 创 建 API 的 测试 ， 也 就 是 提交 POST 请 求人 到“/design”: 


QTest 
public void shouldSaveATaco() { 
TacoRepository tacoRepo = Mockito.mock( 
TacoRepository.class); 一 --- 搭建 测试 数据 
Mono<Taco> unsavedTacoMono = Mono.just(testTaco(null)); 
Taco savedTaco = testTaco(null); 
savedTaco.setId(1L ) ; 
Mono<Taco> savedTacoMono = Mono.just(savedTaco ) ; 
when(tacoRepo.save(any() ) ) .thenReturn(savedTacoMono ) ; 人 一 --- mock Tac 
oRepository 


WebTestClient testClient = WebTestClient.bindToController( 一 --- 创建 W 
ebTestClient 
new DesignTacoController(tacoRepo)).build(); 


testClient.post() 人 一--- POST taco 

.Uri("/design") 
.CcontentType(MediaType.APPLICATION JSON) 
.body (unsavedTacoMono, Taco.class) 

.exchange() 

.expectSstatus().isCreated() 一 --- 校 验 啊 应 

.expectBody(Taco.class) 
.isEqualTo(savedTaco); 





与 上 面 的 测试 方法 类 似 ，shouldSaveATaco0 首 先 会 创建 一 些 测 试 数 
据 和 mock TacoRepository， 并 且 创 建 了 一 个 WebTestClient 并 绑 定 到 控制 
器 上 上 。 随 后 ， 它 使 用 WebTestClient 提 交 POST 请 求 到 “/design”， 并 且 将 


请 求 体 声明 为 application/json 攻 型， 请 求 载 和 傈 为 Taco 的 JSON 订 列 化 形 
式 ， 放 到 未 保存 的 Mono 中 。 在 执行 exchange0 之 后 ， 测 斌 断言 啊 应 状态 
为 HTTP 201 (CREATED) 并 且 啊 应 体 中 的 载 向 与 已 保存 的 Taco 对 象 相 

同 。 


11.3.3 ”使 用 实时 服务 器 进行 测试 


到 目前 为 止 ， 我们 所 编写 的 测试 都 依赖 于 Spring WebFlux 的 mock 实 
现 ， 所 以 并 不 需要 真正 的 服务 左 。 但 是 ， 我 们 可 能 需要 在 服务 项 《〈 如 
Netty 或 Tomcat) 环境 中 测试 WebFlux 控 制 闫 ， 也 许 还 会 需要 repository 或 
其 他 的 依赖 。 换 人 句 话 说 ， 我 们 有 可 能 要 编写 集成 测试 。 


要 编写 WebTestClient 的 集成 测试 ， 与 其 他 的 Spring Boot 集 成 测试 炎 
似 ， 我 们 首先 要 为 测试 医 未 加 @RunWith 和 人 @SpringBootTest: 


QORunWwith(SpringRunner .class ) 
QOSpringBootTest(webEnvironment=WebEnvironment .RANDOM PORT) 
public class DesignTacoControllerWebTest { 


Q@Autowired 
private WebTestClient testClient; 





通过 将 webEnvironment 属 性 设置 为 
WebEnvironment.RANDOM_PORT， 我 们 要 求 Spring 启 动 一 个 运行 时 服 
务 器 并 监听 任意 选择 的 端口 呈 。 


你 可 能 也 注意 到 ， 我 们 将 WebTestClient 自 动 织 入 到 了 测试 类 中 。 这 


不 仅 意 味 看 我 们 不 用 在 测试 的 方法 中 创建 它 了 ， 而 且 在 发 运 请 求 的 时 低 
也 不 需要 指定 完整 的 URL 了 。 这 是 因为 WebTestClient 能 够 知道 测试 服务 
俐 在 哪个 端口 上 运行 。 现 在 ， 我 们 可 以 使 用 目 动 织 入 的 WebTestClient 将 
shouldReturnRecentTacos0) 重 写 为 集成 测试 : 


QTest 
public void shouldReturnRecentTacos() throws IOException { 
testClient.get().uri("/design/recent") 
.accept(MediaType.APPLICATION JSON) .exchange' ) 
.expectStatus().isOk() 
.exXpectBody() 


.jsonPpath("$[?(@.id == 'TACO1' )].name") 
.ijsEqualTo("Carnivore") 

.jsonPpath("$[?(@.id == 'TACO2')].name") 
.ijsEqualTo("Bovine Bounty") 

.jsonPpath("$[?(@.id == 'TACO3"')].name") 
.ijsEqualTo("Veg-Out" ); 





我 们 发 现 ， 这 个 狐 版 本 的 shouldReturnRecentTacos() 代 人 码 要 少 得 
多 。 我 们 不 再 需要 创建 WebTestClient， 因 为 可 以 使 用 自动 织 入 的 实例 。 
另外 ， 也 不 需要 mock TacoRepository， 因 为 Spring 将 会 创建 
DesignTacoController 实 例 并 将 一 个 真正 的 TacoRepository 注 入 进来 。 在 
新 版 本 的 测试 方法 中 ， 我 们 使 用 JSONPath 表 达 式 来 校 验 数据 库 提 供 的 
值 。 


WebTestClient 在 测试 的 时 候 非 党 有 用 ， 此 时 我 们 会 消 宪 WebFlux 控 
制 慌 所 骏 露 的 API。 但 是 ， 如 采 我 们 的 应 用 本 喘 要 消费 茶 个 API， 又 该 
怎样 处 理 呢 ? 接 下 来 ， 我 们 将 注意 力 转 同 Spring 肥 应 式 Web 的 客户 并 
看 一 个 WebClient 如 何 通 过 REST 客 户 站 来 处 理 反 应 式 闫 型， 如 Mono 和 
Flux。 


11.4 反应 陈 消 绚 REST API 


在 第 7 章 中 ， 我 们 使 用 RestTemplate 有 友 送 澡 户 疾 请 求 到 Taco Cloud 
API 上 。RestTemplate 有 看 很 久 的 历史 ， 从 Spring 3.0 版 本 束 引 入 了 。 我 
们 曾经 使 用 它 为 应 用 及 送 了 无 数 的 请 求 ， 但 是 RestTemplate 捉 供 的 方法 
处 理 的 都 是 非 反 应 式 领 域 类 型 和 集合 。 这 意味 看 ， 如 采 我 们 想 要 以 反应 
式 的 方式 使 用 啊 应 数据 ， 束 前 要 使 用 Flux 或 Mono 对 其 进行 包装 。 如 来 
我 们 已 经 有 了 Flux 或 Mono， 想 要 通过 POST 或 PUT 请 求 友 壕 它们， 那么 
我 们 震 要 在 发 庆 请 求 之 前 将 数据 抽取 到 一 个 非 反 应 式 的 类 型 中 。 


如 果 能 够 有 一 种 方式 让 RestTemplate 原 生 使 用 反应 式 类 型 那 就 好 
了 。 不 用 担心 ，Spring 5 提供 了 WebClient， 它 可 以 作为 RestTemplate 的 
有 反应 式 版 本 。WebClient 能 够 让 我 们 请 求 外 部 API 时 发 送 和 接收 反应 式 类 


型 。 


WebClient 的 使 用 方式 与 RestTemplate 有 很 大 的 差别 。RestTemplate 
会 有 多 个 方法 处 理 不 同类 型 的 请 求 ;， 而 WebClient 有 一 个 流畅 (fluent) 
的 构建 者 风格 接口 ， 能 够 让 我 们 摘 述 和 有 友 送 请 求 。WebClient 的 通用 使 
用 模 却 如 下 : 


。 创建 WebClient 实 例 〈( 或 注入 WebClient bean ) ; 
。 指定 要 友 送 请 求 的 HTTP 方 法 ; 

。 指定 请 求 中 URI 和 头 信息 ; 

。 提交 请 求 ; 

。 消 避 啊 应 。 


接 下 来 ， 我 们 实际 看 几 个 WebClient 的 例子 ， 首 先 从 如 何 使 用 
WebClient 发 送 HTTP GET 请 求 开 始 。 


11.4.1 多 取 资源 





作为 使 用 WebClient 的 样 例 ， 假 设 我 们 需要 通过 Taco Cloud API 根 据 
ID 获取 Ingredient 对 象 。 如 果 使 用 RestTemplate， 那 么 我 们 可 能 会 使 用 
getForObject() 方 法 。 但 是 ， 借 助 WebClient 的 话 ， 我 们 会 构建 请 求 、 获 
取 啊 应 并 抽取 一 个 会 发 布 ingredient 对 象 的 Mono: 


Mono<Ingredient> ingredient = WebClient.createl() 
.get( ) 
.Uri("http://localhost:8060806/ingredients/{id}", ingredientId) 


.retrievel() 
.bodyToMono(Ingredient.class); 





ingredient.subscribe(i -> { ... }) 


在 这 里 ， 我 们 使 用 create0 创 建 了 一 个 新 的 WebClient 实 例 。 然 后 ， 
我 们 使 用 get0 和 uriO 定 义 对 http:Mlocalhost:808O/ingredients/fid} 的 GET 请 
求 ， 其 中 {fid} 占 位 符 将 会 被 imgredientId 的 值 所 替换 。 接 着 ，retrieve0) 会 
执行 请 求 。 最 后 ， 我 们 调用 bodyToMonog0 将 啊 应 体 的 载荷 抽取 到 
Mono<Ingredient> 中 ， 束 可 以 继续 使 用 Mono 的 额外 操作 了 。 


为 了 对 bodyToMono0O 返 回 Mono 进 行 额外 的 操作 ， 需 要 注意 的 很 重 
要 的 一 点 是 要 在 请 求 友 送 之 本 对 其 进行 订阅 。 发 迷 请 求 获取 值 的 集合 是 
韭 常 容易 的 。 例 如 ， 如 下 的 代码 厂 段 将 锋 取 所 有 配料 : 


FluxcIngredient> ingredients = WebClient.createl() | 


.get() 
.uri("http://localhost:806806/ingredients") 
.retrievel() 

.bodyToF lux(Ingredient.class); 


ingredients.subscribe(i -> { ... }) 





大 部 分 而 言 ， 获 取 多 个 条 上 日 与 获取 单个 条 目 是 相同 的 。 最 大 的 甘 异 
在 于 我 们 不 再 是 使 用 bodyToMono() 将 啊 应 体 抽取 为 Mono， 而 是 使 用 
bodyToFlux() 将 其 抽取 为 一 个 Flux。 


与 bodyToMono() 类 似 ，bodyToFlux0O 返 回 的 Flux 还 没有 人 被 订阅 。 在 
Pe 之 前 ， 我 们 可 以 对 Flux 洪 加 一 些 额 外 的 操作 (过 小 、 映 映 

。 因 些 ， 非 党 重要 的 一 点 就 是 要 订阅 结果 所 形成 的 Flux， 合 则 请 求 
将 始终 不 会 及 大。 


使 用 基础 URI 发 送 请 求 


你 可 能 会 发 现在 很 多 请 求 中 都 会 使 用 一 个 通用 的 基础 URI。 这 样 的 
话 ， 创 建 WebClient bean 的 时 候 设 置 一 个 基础 URI 并 将 其 注入 到 所 需 的 地 
方 是 非常 有 用 的 。 这 样 的 bean 可 以 按照 如 下 的 方式 来 声明 : 


QBean 
public WebClient webClient() { 


return WebClient.create("http://localhost:80680"); 
} 





然后 ， 在 想 要 使 用 基础 URI 的 任意 地 方 ， 我 们 都 可 以 将 WebClient 
bean 注 入 进来 并 按照 如 下 的 方式 来 使 用 : 


QAutowired 
WebClient webClient; 


public Mono<Ingredient> getIngredientById(String ingredientId) { 
Mono<Ingredient> ingredient = webClient 
.2et() 
.Uri("/ingredients/{id}", ingredientId) 
.retrievel() 
.bodyToMono(Ingredient.class ) ; 


ingredient.subscribe(i -> { ... }) 


} 





为 WebClient 已 经 创建 好 了 ， 上 所 以 我 们 可 以 通过 get0 方 法 直接 使 
用 它 。 对 于 URI 来 说 ， 我 们 只 需要 调用 uriO0 指 定 相 对 于 基础 URI 的 相对 
路 径 即 可 。 


对 长 时 间 运 行 的 请 求 进行 超时 处 理 


我 们 需要 考虑 的 一 件 事情 束 古 ， 网 络 并 不 是 始终 可 徘 的 ， 或 者 并 不 
像 我 们 预期 的 那么 快 ， 远 程 服 务 需 在 处 理 请 求 时 有 可 能 会 非 营 组 怪 。 理 
想 情 况 下 ， 对 远程 服务 的 请 求 会 在 一 个 合理 的 时 间 内 返回 。 无 法 正 剃 返 
加 的 话 ， 各 户 靖 要 是 能 够 避免 陷入 长 时 间 等 待 啊 应 的 敌 境 融 好 了 。 


为 了 避免 客户 跨 请求 被 绥 怪 的 网 络 或 服务 阻 时 ， 我 们 可 以 使 用 Flux 
或 Mono 的 timeout0 方 法 ， 为 等 竺 数据 友 布 的 过 程 设 置 一 个 时 长 限制 。 作 
为 样 例 ， 我 们 考虑 一 下 如 何 为 获取 配料 数据 使 用 timeout() 方 法 : 





Flux<Ingredient> ingredients = WebClient.create'( ) 
‘get() 
.Uri("http://localhost:8060806/ingredients") 
.retrievel() 

.bodyToFlux(Ingredient.class); 


ingredients 
.timeout(Duration.ofSeconds(1)) 
.Subscribel 


1 SY. 


e -> { 
// handle timeout error 


}) 


可 以 看 人 到， 在 订阅 Flux 之 前 ， 我 们 调用 了 timeout0 方 法 ， 将 持续 时 
间 设 置 成 了 1 秒 。 如 果 请 求 能 够 在 1 秒 之 内 返回 ， 残 不 会 有 任何 问题 。 如 
果 请 求 的 耗 时 超过 1 秒 ， 束 会 超时 ， 作 为 第 二 个 参数 传递 给 subscribe() 的 
铬 误 处 理 右 将 会 裤 调 用 。 


11.4.2 发 送 资源 


使 用 WebClient 友 送 数据 与 接收 数据 并 没有 太 大 的 差异 。 作 为 样 
例 ， 假 设 我 们 有 一 个 Mono<Ingredient>， 并 且 想 要 将 Mono 发 布 的 
Ingredient 对 象 以 POST 请 求 的 形式 发 大 到 相对 路 径 %ingredients” 的 URI 
上 。 我 们 所 需要 做 的 就 是 使 用 post0 方 法 来 蔡 换 get0， 并 通过 body() 方 法 
指明 要 使 用 Mono 来 填充 请 求 体 : 


Mono<Ingredient> ingredientMono = ...; 


Mono<Ingredient> result = webClient 


.post() 
.Uri("/ingredients") 


.body(ingredientMono, Ingredient.class) 
.retrievel() 
.bodyToMono(Ingredient.class ) ; 


result.subscribe(i -> { ... }) 





如 果 我 们 没有 要 发 送 的 Mono 或 Flux， 而 只 有 原始 的 领域 对 象 ， 那 
么 可 以 使 用 syncBody0 方 法 。 例 如 ， 假 设 我 们 没有 Mono<Ingredient>， 
而 是 有 一 个 想 要 在 请 求 体 中 发 送 的 Ingredient 对 象 ， 那 么 可 以 这 样 做 : 


Ingedient ingredient = ...; 


Mono<Ingredient> result = webClient 


.post() 
.Uri("/ingredients") 


.SyncBody(ingredient) 
.retrievel() 
.bodyToMono(Ingredient.class ) ; 





result.subscribe(i -> { ... }) 


如 采 我 们 不 是 使 用 POST 请 求 ， 而 是 想 要 使 用 PUT 请 求 更 新 一 个 
Ingredient， 残 可 以 使 用 put0 来 蔡 换 post)， 并 相应 地 调整 URI 路 径 : 


Mono<Void> result = webClient 


.put() 
.Uri("/ingredients/{id}", ingredient.getId()) 


.SyncBody(ingredient) 
.retrievel() 
.bodyToMono(Void.class ) 
.SUbscribe() ; 





PUT 请 求 的 啊 应 载 傈 一 般 是 空 的 ， 所 以 我 们 必须 要 求 bodyToMono() 
返回 一 个 Void 类 型 虹 Mono。 一 旦 订阅 该 Mono， 请 求 束 会 立即 友 运 。 


11.4.3 删除 资源 


WebClient 还 文 持 通 过 其 delete0) 方 法 移 除 资产。 人 例如， 根据 ID 删除 
配料 : 


Mono<Void> result = webClient 
.deletel() 
.Uri("/ingredients/{id}", ingredientId) 


.retrievel() 
.bodyToMono(Void.class ) 
.SUbscribe() ; 





与 PUT 请 求 类 似 ，DELETE 请 求 的 啊 应 不 会 有 载荷 。 同 样 ， 我 们 返 
回 并 订阅 Mono<Void> 束 会 发 送 请 求 。 


11.4.4 ”处理 错误 


到 目前 为 止 ， 所 有 的 WebClient 样 例 都 假设 有 一 个 正 稼 的 结果 : 没 
有 400 级 别 和 500 级 别 的 状态 码 。 如 果 出 现 这 两 种 类 型 的 错误 状态 ， 
WebClient 束 会 记录 失败 信息 ; 否则 ， 束 会 默默 忽略 挥 。 


如 采 你 需要 处 理 这 种 错误 ， 那 么 可 以 调用 onStatus(0) 来 指定 各 种 类 型 
的 HTTP 状 态 码 该 如 何 进 行 处 理 。onStatus(0) 接 受 两 个 函数 : 一 个 断言 函 
数 用 来 下 配 HTTP 状 态 ， 男 一 个 函数 会 得 到 ClientResponse 对 象 ， 并 返回 


Mono<Throwable>。 


为 了 阐述 如 何 使 用 onStatus0O 创 建 目 定义 的 错误 处 理 器 ， 请 参考 如 下 
使 用 WebClient 根 据 ID 获 取 配 料 的 样 例 : 


Mono<Ingredient> ingredientMono = webClient 
.get() 


.Uri("http://localhost:8060806/ingredients/{id}", ingredientId) 
.retrievel() 
.bodyToMono(Ingredient.class ) ; 





如 果 ingredientId 的 值 能 够 匹配 已 知 的 资源 ， 那 么 结果 得 到 的 Mono 
在 订阅 时 就 会 发 布 一 个 Ingredient。 但 是 ， 如 果 找 不 到 匹配 的 配料 呢 ? 


当 订 陪 可 能 会 出 现 错误 的 Mono 或 Flux 时 ， 很 重要 的 一 点 就 是 在 调 
用 subscribe() 注 册 数 据 消费 者 的 同时 ， 也 要 注册 一 个 错误 消费 者 : 


ingredientMono .subscribe( 
ingredient -> 1{ 
// handle the ingredient data 


// deal with the error 


D> 





如 果 能 够 找到 配料 资源 ， 那 么 传递 给 subscribe() 的 第 一 个 lambda 表 
达 式 《数据 消费 者 ) 将 会 航 调 用 ， 并 且 会 将 匹配 的 Ingredient 对 象 传递 过 
来 。 但 是 ， 如 果 找 不 到 资源 ， 那 么 请 求 将 会 得 到 一 个 HTTP 404 (NOT 
FOUND) 状 态 人 码 的 啊 应 ， 它 将 会 导致 第 二 个 lambda 表 达 式 (错误 消费 
者 ) 被 调用 ， 并 且 会 传 违 过 来 一 个 献 认 的 


WebClientResponseException。 


WebClientResponseException 最 大 的 问题 在 于 它 无 法 明确 指出 导致 
Mono 和 撩 败 的 原因 是 什么 。 筷 的 名 字 表 明 在 WebClient 及 起 的 请 求 中 ， 出 
现 了 啊 应 错误 ， 但 是 我 们 需要 深入 研究 WebClientResponseException 才 
能 知道 哪里 出 现 了 了 错误。 无论 如 何 ， 如 果 给 错误 消费 者 的 弄 音 更 加 专注 
业务 领域 而 不 是 专注 WebClient， 那 就 更 好 了 。 


我 们 可 以 添加 一 个 日 定义 的 错误 处 理 费 ， 在 这 个 处 理 右 中 可 以 提供 
将 状态 码 转 换 为 自己 所 选择 的 Throwable 的 代码 。 如 果 请 求 配料 资源 时 
得 到 的 Mono 失 败 ， 我 们 就 生成 一 个 UnknownIngredientException。 在 调 
用 retrieve0 之 后 ， 我 们 可 以 这 加 一 个 对 onStatusO 的 调用 ， 从 而 实现 这 一 
Es 


MonocIngredient> ingredientMono = webClient | 


.get() 
.Uri("http://localhost:8060806/ingredients/{id}", ingredientId) 
.retrievel() 
.onStatus(HttpStatus::is4xxClientError., 

response -> Mono.just(new UnknownIngredientException())) 
.bodyToMono(Ingredient.class ) ; 





调用 onStatusO 时 第 一 个 参数 是 断言 ， 它 会 接 党 一 个 HttpStatus， 如 
于 状态 码 征 我 们 想 要 处 理 的 ， 驶 将 会 返回 true。 如 末 状 态 码 匹配 ， 啊 应 
将 会 传递 给 第 二 个 参数 的 图 数 并 按 需 进行 处 理 ， 最 终 返 回 Throwable 关 
型 的 Mono。 


在 样 例 中 ， 如 果 状 态 码 是 400 级 别 的 《比如 客户 闹 错 误 〉 ， 那 么 将 
会 返回 包含 UnknownIngredientException 的 Mono。 这 会 导致 


ingredientMono 因 为 该 异 第 而 失败 。 


需要 注意 ，HttpStatus::is4xxClientError 是 对 HttpStatus 的 
is4xxClientError 的 方法 引用 。 此 时 ， 将 会 基于 HttpStatus 对 象 调 用 该 方 
法 。 如 果 喜 欢 ， 还 可 以 使 用 HttpStatus 的 其 他 方法 作为 方法 引用 。 你 也 
可 以 以 lambda 表 达 式 或 方法 引用 的 形式 提供 其 他 返回 boolean 类 型 的 函 
数 。 


例如 ， 在 错误 处 理 中 ， 我 们 可 以 更 加 精确 地 检查 HTTP 404 (NOT 
FOUND) 状 态 ， 只 需 将 对 onStatusO 的 调用 修改 成 如 下 形式 即 可 : 


Mono<Ingredient> ingredientMono = webClient 
.get( ) 
.Uri("http://localhost:8060806/ingredients/{id}", ingredientId) 


.retrievel() 
.OnStatus(status -> status == HttpStatus.NOT FOUND, 

response -> Mono.just(new UnknownIngredientException())) 
.bodyToMono(Ingredient.class ) ; 





全 得 一 提 的 征 ， 我 们 可 以 鬼 需 调用 onStatus0 任 意 多 次 ， 以 便于 处 理 
啊 应 中 可 能 返回 的 各 种 HITP 状 态 但 。 


11.4.5 ”交换 请 求 


到 目前 为 止 ， 在 使 用 WebClient 的 时 候 ， 我 们 都 是 利用 它 的 retrieve() 
方法 来 发 送 请 求 。 在 这 ee 中 ，retrieve0) 方 法 会 返回 一 个 
ResponseSpec 关 型 的 对 象 ， 通 过 调用 它 的 onStatusO0、bodyToFlux0O 和 
bodyToMono0) 方 法 ， 我 们 融 能 处 理 啊 应 。 对 于 人 简单 的 场景 来 说 ， 使 用 
ResponseSpec 隋 足够 了 了， 但 是 它 在 很 多 方面 都 有 局 限 性 。 如 采 我 们 想 要 
访问 啊 应 的 头 信 息 或 cookie 的 值 ， 那 么 ResponseSpec 磺 无 能 为 力 了 。 


在 使 用 ResponseSpec 过 到 | 困难 时 ， 我 们 就 可 以 通过 调用 exchange() 
方法 来 蔡 换 retrieve() 方 法 。exchange() 方 法 会 返回 ClientResponse 类 型 的 
Mono， 我 们 可 以 对 它 采 用 各 种 反应 式 操作 ， 以 便于 探 击 和 使 用 整个 啊 
应 中 的 数据 ， 包 括 载 傈 、 头 信息 和 cookie。 


在 了解 exchange() 和 retrieve() 的 大 寞 之 前 ， 我 们 先 看 一 下 它们 之 间 的 
相似 之 处 。 如 下 的 代码 片段 通过 WebClient 和 exchange() 方 法 ， 根 据 ID 获 
取 单 个 配料 : 


Mono<Ingredient> ingredientMono = webClient 
.get() 


.Uri("http://localhost:8060806/ingredients/{id}", ingredientId) 
.exchange() 
.flatMap(cr -> cr.bodyToMono(Ingredient.c]lass)); 





这 几乎 与 使 用 retrieveO 的 样 例 是 相同 的 : 


Mono<Ingredient> ingredientMono = webClient 
.get() 


.Uri("http://localhost:8060806/ingredients/{id}", ingredientId) 
.retrievel() 
.bodyToMono(Ingredient.class ) ; 





在 exchange() 样 例 中 ， 我 们 不 是 使 用 ResponseSpec 对 和 象 的 
bodyToMono() 方 法 来 获取 Mono<Ingredient>， 而 是 得 到 了 一 个 
Mono<ClientResponse>， 通 过 它 我 们 可 以 执行 局 平 化 映 昧 (flat- 
mapping) 浮 数 ， 将 ClientResponse 映 碳 为 Mono<Ingredient>， 这 样 局 平 
化 为 最 终 力 要 的 Mono。 


现在 ， 我 们 看 一 下 exchange() 的 差 寞 在 什么 地 方 。 假 设 请 求 的 啊 应 
中 会 包含 一 个 名 为 X_UNAVAILABLE 的 头 信息 ， 如 果 它 的 值 为 tue， 则 
表明 该 配料 是 不 可 用 的 《因为 某 种 原因 ) 。 为 了 讨论 方便 ， 假 设 如 果 这 
个 头 信 息 存 在 ， 那 么 我 们 希望 得 到 的 Mono 是 空 的 ， 不 返回 任何 内 容 。 
人 通过 添加 男 外 一 个 flatMap0 调 用 ， 我 们 束 能 实现 这 一 点 。 整 个 的 
WebClient 调 用 过 程 如 下 所 示 : 
Mono<Ingredient> ingredientMono = webClient 

.2et() 

.uri("http://localhost:86806/ingredients/{id}", ingredientId) 


.exchange() 
.flatMap(cr -> { 


if (cr.headers().header("X UNAVAILABLE").contains("true")) { 
return Mono.empty(); 


} 


return Mono.just(cr); 


}) 
.flatMap(cr -> cr.bodyToMono(Ingredient.class)); 





新 的 flatMapO 调 用 会 探查 给 定 ClientRequest 对 象 的 啊 应 头 ， 查 看 是 
否 存 在 值 为 true 的 X_UNAVAILABLE 头 信息 。 如 果 能 够 找到 ， 就 将 会 返 


回 一 个 空 的 Mono; 人 否则 ， 返 回 一 个 包含 ClientResponse 的 新 Mono。 不 管 
是 哪 种 情况 ， 返 回 的 Mono 都 会 扁平 化 为 下 一 个 flatMap() 操 作 所 要 使 用 
的 Mono。 


11.5 ”保护 反应 式 Web API 


从 Spring Security 诞 生 以 来 〈 甚 至 可 以 退 调 到 它 叫 作 Acegi Security 
的 时 代 ) ， 它 的 web 安全 模型 融 是 基于 Servlet Filter 构 建 的 。 毕 竟 ， 这 样 
做 是 有 道理 的 。 如 采 我 们 希望 拦截 基于 Servlet 技 术 的 Web 框 如 的 请 求 ， 
以 确 傈 该 请 求 得 到 了 恰当 的 授权 ， 那 么 Servlet Filter 是 显 而 多 见 的 方 
案 。 但 是 ，Spring WebFlux 并 不 适用 于 这 种 方式 。 


在 使 用 Spring WebFlux 编 写 Web 应 用 的 时 候 ， 我 们 甚至 都 不 能 你 证 
会 用 到 Servlet。 实 际 上 ， 反 应 式 Web 应 用 很 有 可 能 构建 在 Netty 或 其 他 非 
Servlet 容 需 上 。 这 是 人 否 意 味 独 基于 Servlet Filter 的 Spring Security 个 能 
来 保护 我 们 的 Spring WebFlux 应 用 了 呢 ? 


在 你 护 Spring WebFlux 应 用 的 时 候 ，Servlet Filter 确 实 不 是 可 行 方 案 
了 。 但 是 ，Spring Security 依 然 可 以 胜任 这 项 任务 。 从 5.0.0 版 本 开始 ， 
Spring Security 就 既 能 保护 基于 Servlet 的 Spring MVC， 又 能 保护 反应 式 
的 Spring WebFlux 应 用 了 。 在 实现 这 一 点 的 时 候 ， 它 使 用 了 Spring 的 
WebFilter， 这 是 Spring 模 仿 Servlet Filter 的 类 似 方案 ， 但 是 它 不 依赖 于 
Servlet API。 


然而 ， 更 值得 注意 的 是 ， 反 应 式 Spring Security 的 配置 模型 与 在 第 4 


章 中 看 到 的 没有 太 大 不 同 。 事 实 上 ，Spring WebFlux 与 Spring MVC 有 着 
独立 的 依赖 关系， 但 与 之 不 同 ，Spring Security 古 作为 同一 个 Spring Boot 
Security starter 提 供 的 ， 不 管 你 是 打算 使 用 它 来 保护 Spring MVC Web 应 
用 ， 还 是 保护 使 用 Spring WebFlux 编 写 的 应 用 ， 都 需要 添加 这 项 依赖 。 
提醒 一 下 ，security starter 如 下 所 示 : 


<dependency> 
<groupId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-security</artifactId> 
</dependency> 





也 束 是 说 ，Spring Security 的 反应 式 和 非 反 应 式 配 置 模型 仪 有 几 项 
很 小 的 差异 。 我 们 很 有 必要 快速 对 比 一 下 这 两 种 配置 模型 。 


11.5.1 配置 反应 式 Web 应 用 的 安全 性 


回忆 一 下 ， 配 置 Spring Security 来 保护 Spring MVC Web 悄 用 通 弟 需 
要 创建 一 个 扩展 自 WebSecurityConfigurerAdapter 的 新 配置 类 ， 并 使 用 
@EnableWebSecurity 注 解 。 这 样 的 配置 类 将 重 写 configuration0) 方 法 ， 以 
指定 Web 安 全 的 细 和 有 ， 例 如 特定 的 请 求 路 径 需 要 哪些 权限 。 下 面 这 个 简 
单 的 Spring Security 配 置 类 可 以 帮助 我 们 回忆 如 何 为 非 反 应 式 Spring 
MVC 应 用 配置 安全 性 : 





@Configuration 
@EnableWebSecurity 
public class SecurityConfig extends WebSecurityConfigurerAdapter 1{ 


QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 


.authorizeRequests'( ) 
.antMatchers("/design", "/orders").hasAuthority("USER") 
.antMatchers("/**").permitAll(); 





现在 ， 我 们 看 一 下 相同 的 配置 如 何 用 到 反应 式 Spring WebFlux 应 用 
中 。 程 序 清 单 11.2 展 现 了 一 个 反应 去 安全 配置 闫 ， 它 的 功能 与 前 文 的 安 
全 配置 大 致 相同 : 


程序 清单 11.2 ”为 Spring WebFlux 配 置 Spring Security 


@Configuration 
@EnableWebFluxSecurity 
public class SecurityConfig { 


QBean 
public SecurityWebFilterChain securityWebFilterChaint( 


ServerHttpSecurity http) { 
return http 


.authorizeExchange() 
.pathMatchers("/design", "/orders").hasAuthority("USER") 
.anyExchange( ).permitAll() 
.and() 
.build(); 





我 们 可 以 看 到 ， 有 很 多 类 似 的 地 方 ， 同 时 也 有 所 和 友和 寞 。 这 个 狐 的 配 
置 类 没有 使 用 @EnableWwebSecurity， 而 是 使 用 了 
@EnableWebFluxSecurity 注 解 。 除 此 之 外 ， 配 置 英 没有 扩展 
WebSecurityConfigurerAdapter 或 其 他 的 其 类 ， 因 此 也 就 没有 必要 重 写 


configure()。 


为 了 取代 configure() 的 功能 ， 我 们 通过 securityWebFilterChain() 方 法 


声明 了 一 个 SecurityWebFilterChain 关 型 的 bean。securityWebFilterChain() 
的 方法 体 与 前 面 配 置 的 configure(0) 方 法 没有 太 大 的 差异 ， 但 是 也 有 略微 
的 修改 。 


最 重要 的 是 ， 配 置 是 通过 给 定 的 ServerHttpSecurity 对 象 进 行 声 明 
的 ， 而 不 是 通过 HttpSecurity 对 象 。 倍 助 ServerHttpSecurity， 我 们 可 以 调 
用 authorizeExchange0， 它 大 致 等 价 于 authorizeReduests0)， 者 是 用 来 声 
明 请 求 级 的 安全 性 的 。 


注意 : ServerHttpSecurity 是 Spring Security 5 新 引入 的 ， 在 反 


应 式 编 程 中 它 模拟 了 HttpSecurity 的 功能 。 





在 映射 路 径 的 时 候 ， 我 们 依然 可 以 使 用 Ant 风 格 的 通配符 路 径 ， 但 
是 这 里 要 使 用 pathMatchers()， 而 个 是 antMatchers()。 这 样 做 的 结果 就 
是 ， 我 们 不 再 需要 声明 Ant 风 格 的 路 人 径 “/**” 来 捕获 所 有 请 求 ， 因 为 
anyExchange0O 会 映射 所 有 的 路 径 。 


最 后 ， 因 为 我 们 将 SecurityWebFilterChain 声 明 为 一 个 bean， 而 不 是 
重 写 框架 方法 ， 所 以 我 们 需要 调用 build0) 方 法 将 所 有 的 安全 规则 聚合 到 
一 个 要 返回 的 SecurityWebFilterChain 对 和 象 中 。 


除了 这 些微 小 的 差异 外 ， 配 置 Spring WebFlux 和 Spring MVC 的 Web 
安全 性 并 没有 太 多 不 同 。 那 么 如 何 获 取 用 户 的 详情 信息 呢 ? 


11.5.2 ”配置 反应 陈 的 用 户 详情 服务 


在 扩展 WebSecurityConfigurerAdapter 的 时 候 ， 我 们 会 重 写 
configure0 方 法 以 声明 安全 规则 ， 并 且 还 会 重 与 另外 一 个 configure() 方 法 
来 配置 认证 多 辑 ， 通 章 这 需要 定义 一 个 UserDetails。 为 了 提醒 一 下 代 但 
会 是 什么 样子 ， 如 下 的 代码 重 写 了 configure() 方 法 ， 并 日 在 
UserDetailsService 的 匿名 实现 中 ， 使 用 了 注入 的 UserRepository 对 象 以 所 
供 和 根据 用 户 名 碍 找 用 户 的 功能 
@Autowired 

UserRepository userRepo; 


QOverride 
protected void 
configure(AuthenticationManagerBuilder auth) 
throws Exception { 
auth 
.USerDetailsService(new UserDetailsService() { 
QOverride 


public UserDetails loadUserByUsername(String username) 
throws UsernameNotFoundException { 
User user = userRepo.findByUsername(username) 
if (user == null) { 
throw new UsernameNotFoundException( 
Username ”+ not found") 


} 


return user.toUserDetails(); 





在 这 个 非 反 应 式 的 配置 中 ， 我 们 重 写 了 UserDetailsService 唯 一 要 求 
的 方法 ， 也 就 是 loadUserByUsername()。 在 这 个 方法 内 部 ， 我 们 使 用 给 
定 的 UserRepository， 实 现 根 据 用 户 名 来 查找 用 户 的 功能 。 如 果 没 有 找 


到 该 名 称 的 用 户 ， 就 会 搜 出 UsernameNotFoundException。 如 果 能 人 够 找 
到， 束 调 用 一 个 辅助 方法 toUserDetails()， 返 回 最 终 的 UserDetails 对 象 。 


在 反应 式 的 安全 配置 中 ， 我 们 不 青草 写 configure() 方 法 ， 而 是 声明 
一 个 ReactiveUserDetailsService bean。 ReactiveUserDetailsService 古 
UserDetailsService 有 的 反应 式 等 价 形式 。 与 UserDetailsService 类 似 ， 
ReactiveUserDetailsService 只 需要 实现 一 个 方法 。 具 体 来 讲 ， 就 是 一 个 
返回 Mono<UserDetails> 的 findByUsername() 方 法 ， 这 里 返回 的 不 再 是 
UserDetails 对 象 。 


在 下 面 的 样 例 中 ，ReactiveUserDetailsService bean 会 给 定 一 个 
UserRepository， 我 们 假设 它 是 一 个 反应 陈 的 Spring Data repository 在 
第 12 草 我 们 将 会 详细 讨论 ) : 


QService 
public ReactiveUserDetailsService userDetailsServicel 
UserRepository userRepo) { 
return new ReactiveUserDetailsService() { 
QOverride 
public Mono<UserDetails> findByUsername(String username) { 


return userRepo.findByUsername(username) 
.map(user -> { 
return user.toUserDetails(); 


}); 





在 这 里 ， 按 需要 返回 一 个 Mono<UserDetails>， 但 是 
UserRepository.findByUsername0 方 法 所 返回 的 是 Mono<User>。 因 为 它 
是 一 个 Mono， 所 以 可 以 对 它 进 行 链 式 操作 ， 比 如 进行 map0O 操 作 ， 将 


Mono<User> 有 映射 为 Mono<UserDetails>。 


在 本 例 中 ，map0 操 作 使 用 了 一 个 lambda 表 达 式 ， 它 调用 了 Mono 所 
及 布 的 User 对 象 上 的 toUserDetails0) 方 法 。 这 个 方法 会 将 User 转 换 为 
UserDetails。 这 样 的 话 ，“.map0” 操 作 会 返回 一 个 Mono<UserDetails>， 
恰好 束 古 ReactiveUserDetailsService.findByUsername() 方 法 所 需要 的 。 


11.6 小结 


。 Spring WebFlux 提 供 了 一 个 反应 式 的 Web 框 架 ， 它 的 编程 模型 是 与 
Spring MVC 对 应 的 ， 甚 至 共享 了 很 多 相同 的 注解 。 

。 Spring 5 还 提供 了 函数 式 编 程 模型 ， 作 为 Spring WebFlux 的 蔡 代 方 
案 。 

。 反应 式 控 制 占 可 以 使 用 WebTestClient 来 进行 测试 。 

。 在 客户 疹 ，Spring 5 提供 了 WebClient， 也 束 古 Spring RestTemplate 
的 反应 式 等 价 实 现 。 

。 在 保护 Web 应 用 方面 ， 尽 管 WebFlux 在 底层 有 一 些 区 别 ， 但 是 
Spring Security 5 为 有 反应 式 安 全 所 提供 的 编程 模型 与 非 反 应 式 Spring 
MVC 应 用 相 比 并 没有 特别 大 的 天 看 。 





[1] 我 们 也 可 以 将 webEnvironment 设 置 为 
WebEnvironment.DEFINED_PORT， 并 利用 配置 属性 指定 一 个 端口 ， 但 
是 强烈 建议 不 要 这 样 做 。 这 样 做 的 话 将 会 带 来 并 行 运行 服 务 器 端口 冲突 
的 风险 。 


第 12 章 ”反应 取 持 久 化 数据 


Spring Data 的 反应 陈 repository 


为 Cassandra 和 MongoDB 编 与 反应 陈 repository 


以 有 反应 式 的 方式 使 用 非 反 应 式 的 repository 


Cassandra 的 数据 模型 





在 思考 非 阻 塞 的 反应 | 我 经 常会 想到 
上 下 班 的 高 峰 时 刻 〈rush hour) 。 高 峰 时 刻 是 一 个 很 奇怪 的 名 字 。 每 个 
人 都 急 着 去 他 们 想到 的 地 方 ， mea 第 只 能 几乎 一 动不动 地 坐 在 车 
流 之 中 。 如 果 路 上 没有 其 他 人 ， 我 们 能 够 轻而易举 地 到 达 目 的 地 。 


即便 我 非常 希望 到 达 示 个 地 方 〈 我 没有 阻 竖 ) ， 但 是 这 并 不 意味 看 
路 上 没有 其 他 人 挡 着 我 。 前 面 可 能 有 其 他 司机 发 后 了 唱 蹦 事故 ， 阻 塞 了 
其 他 车 辆 的 通行 。 所 以 即使 我 本 可 以 畅通 无 阻 地 回 到 家 中 ， 但 此 刻 我 也 
只 能 阻塞 在 这 里 等 待 事故 清理 完成 。 


在 前 面 的 章节 中 ， 我 们 看 到 了 如 何 使 用 Spring WebFlux 创 建 反 应 
式 、 非 阻 奢 的 控制 匿 。 这 样 能 够 帮助 我 们 提升 Web 层 的 可 扩展 性 。 但 
征 ， 只 有 当 与 这 些 控 制 硕 协作 的 其 他 组 件 都 是 非 阻 于 的 时 候 ， 它 们 本 丑 
才能 是 非 阻塞 的 。 如 果 我 们 编写 的 Spring WebFlux 控 制 器 依赖 于 阻塞 的 
repository， 那 么 反应 式 控 制 器 需要 阻 突 等 等 它 们 生成 数据 。 


因此 ， 很 重要 的 一 点 在 于 ， 要 让 整个 数据 流 变 成 反应 式 和 非 阻 罕 
的 ， 也 就 是 从 控制 器 直到 数据 库 。 在 本 半 中 ， 我 们 将 会 看 到 如 何 使 用 
Spring Data 编 写 肥 应 式 的 repository， 这 些 repository 与 我 们 在 第 3 章 看 到 
的 编程 模型 非 剃 类似。 我 们 首先 从 整体 上 了 人 解 一 下 Spring Data 对 反应 式 
的 支持 。 


12.1 理解 Spring Data 的 反应 式 概况 


从 Spring Data Kay release train 开 始 ，Spring Data 首 次 提供 对 反应 去 
repository 的 文 持 ， 其 中 包括 使 用 Cassandra、MongoDB、Couchbase 或 
Redis 择 久 化 数据 的 反应 陈 编 程 模型 。 


名 称 的 由 来 


尽管 Spring Data 的 各 个 项 目 都 有 上 自己 的 节 和 双 ,但 是 它们 都 按 


照 一 个 release train 来 进行 发 布 ， 每 个 release train 的 命名 对 应 计算 
机 科学 中 一 个 重要 人 物 的 名 字 。 


这 些 名 字 是 按照 字母 排序 的 ， 比 如 Babbage、Codd、 





Dijkstra、Evans、EFowler、Gosling、Hopper 和 Ingalls。 在 编写 本 
书 的 时 候 ， 最 新 的 release train 版 本 是 Spring Data Kay， 这 是 根据 
Alan Kay 来 命名 的 ，Alan Kay 是 Smalltalk 编 程 语言 的 设计 者 之 


人 





你 可 能 也 友 现 了 ， 在 这 里 我 并 没有 提 到 关系 型 数据 库 或 JPA。 令 人 
遗憾 的 是 ， 目 前 还 没有 对 有 反应 式 JPA 的 支持 。 尺 管 天 系 型 数据 库 依然 是 
行业 中 使 用 最 广泛 的 数据 库 方 采 ， 但 是 要 让 Spring Data JPA 文 持 反 应 式 
编程 模型 ， 需 要 数据 库 和 相关 的 JDBC 都 支持 非 阻塞 的 反应 式 模 型 。 不 
下 的 是 ， 人 至 少 目前 还 不 支持 关系 数据 库 的 反应 式 处 理 。 项 望 这 种 情况 能 
在 不 久 的 将 来 得 到 解决 。 册 


本 章 的 重点 是 使 用 Spring Data 为 文 持 反应 式 模 型 的 数据 库 开 发 使 用 
反应 式 类 型 的 repository。 我 们 首先 对 比 一 下 Spring Data 的 反应 式 模型 和 
非 反 应 式 模 型 。 


12.1.1 Spring Data 反 应 式 本 质 论 


Spring Data 反 应 式 的 本 质 可 以 概括 为 一 句 话 ， 那 就 是 在 反应 式 
repository 的 方法 中 ， 要 接 党 和 返回 Mono 和 Flux， 而 不 是 领域 实体 和 集 
合 。 根 据 配料 闫 型 ， 从 后 端 数据 库 中 获取 Ingredient 对 象 的 repository， 可 
以 声明 为 如 下 的 repository 接 口 : 


Flux<Ingredient> findByType(Ingredient .Type type ) ; 


我 们 可 以 看 到 ， 这 个 findByType0) 方 法 会 返回 Flux<Ingredient>， 而 
不 是 像 对 应 的 非 反 应 式 实现 那样 返回 List<Ingredient> 或 


lterable<Ingredient>。 


类 似 的 ， 在 保存 Taco 的 时 候 ，repository 的 SaveAl10 方 法 签名 如 下 所 
示 : 


<Taco> Flux<Taco> saveAll(Publisher<Taco> tacoPublisher); 


在 本 例 中 ，saveAll0 方 法 接受 一 个 Taco 类 型 的 Publisher〈 可 能 是 
Mono<Taco> 或 Flux<Taco>) 并 人 返回 一 个 Flux<Taco>。 这 与 非 反 应 式 的 
repository 是 个 同 的 ， 它 的 save(0) 方 法 有 直接 处理 领域 类 型 ， 接 受 Taco 对 象 
并 返回 保存 的 Taco 对 象 。 


简 而 言 之 ，Spring Data 的 反应 式 repository 与 我 们 在 第 3 章 看 到 的 
Spring Data 的 非 反 应 式 repository 共 圣 儿 乎 相同 的 编程 柑 型 。 唯 一 重要 的 
区 列 是 ， 反 应 陈 repository 的 方法 接受 和 返回 Flux 和 Mono， 而 不 是 原始 
的 领域 类 型 和 集合 。 


12.1.2 反应 式 和 非 反 应 式 类 型 之 则 的 转换 


在 进一步 研究 如 何 使 用 Spring Data 编 写 反 应 式 repository 之 前 ， 我 们 
看 一 下 如 何 解决 遗留 的 巨大 问题 。 我 们 可 能 已 经 使 用 了 关系 型 数据 库 ， 
将 数据 迁移 至 Spring Data 反 应 式 编程 模型 文 持 的 4 种 数据 库 之 一 是 不 太 
现实 的 ， 那 是 否 就 意味 着 我 们 无 法 在 应 用 中 使 用 反应 式 编 程 了 呢 ? 


从 头 到 尾 使 用 反应 式 模型 (包括 数据 库 层 面 ) 时， 我 们 才能 够 得 到 
反应 式 编程 的 全 部 收益 ， 但 是 在 非 反 应 式 数据 库 之 上 使 用 反应 式 流 的 
话 ， 我 们 也 能 得 到 一 部 分 收益 。 即 便 我 们 所 选择 的 数据 库 不 支持 非 阻塞 
的 反应 式 查询 ， 我 们 依然 可 以 以 阻塞 的 方式 获取 数据 并 将 其 转换 为 反应 
式 类 型 ， 从 而 使 上 游 组 件 从 中 收益 。 


例如 ， 假 设 我 们 正在 使 用 关系 型 数据 库 并 利用 Spring Data JPA 进 行 
持久 化 。 我 们 的 OrderRepository 可 能 会 有 一 个 如 下 签名 的 方法 : 


List<Order> findByUser(User user); 


这 个 方法 会 返回 一 个 非 反 应 式 的 List<Order>， 包 含 给 定 User 的 所 有 
Order 信 息 。 当 findByUser0O 梓 调用 的 时 候 ， 碍 询 执行 的 过 程 中 该 方法 会 
了 咀 窒 ， 结 果 会 收集 到 一 个 List 中 。 因 为 List 并 不 是 反应 式 类 型 ， 所 以 我 们 
不 能 在 它 上 和 面 执行 Flux 提 供 的 任何 操作 。 男 外 ， 如 果 调 用 者 是 控制 笑 ， 
那么 它 无 法 以 反应 式 的 方式 处 理 结 果 ， 实 现 提高 可 扩展 性 的 目的 。 

在 JPA repository 的 阻 至 性 方面 我 们 确实 无 能 为 力 。 但 是， 我 们 可 以 
在 接收 到 非 反 应 式 List 的 时 候 束 将 其 转换 成 Flux， 这 样 我 们 束 可 以 从 这 
里 开始 以 反应 云 的 方式 处 理 结果 了 。 为 了 实现 这 一 点 ， 我 们 可 以 使 用 


Flux.fromlterable(): 


List<Order> orders = repo.findByUser(someUser ) ; 
Flux<Order> orderFlux = Flux.fromIterable(orders); 

与 之 类 似 ， 如 果 我 们 想 要 根据 有 D 获 取 一 个 Order， 我 们 束 可 以 立即 
将 其 转换 为 Mono: 


Order order repo.findById(Long id); 
Mono<Order> orderMono = Mono.just(order); 


通过 使 用 Mono.justO 〇 和 Flux 的 fromIterable()、fromArray( 和 
fromStream() 方 法 ， 我 们 可 以 将 非 反 应 式 阻 睹 代码 隔离 在 repository 中 ， 
在 应 用 的 其 他 地 方 ， 我 们 都 可 以 使 用 反应 式 类 型 。 


那 反 方 癌 怎么 样 昵 ? 如 果 我 们 有 一 个 Mono 或 Flux， 此 时 需要 调用 
非 反 应 式 JPA repository 的 save0) 方 法 又 该 怎么 办 呢 ? 好 消息 是 ，Mono 和 
Flux 都 提供 了 将 它们 发 布 的 数据 抽取 到 领域 类 型 或 Iterable 中 的 操作 。 


例如 ， 假 设 WebFlux 控 制 右 接受 的 是 Mono<Taco>， 那 么 我 们 需要 
使 用 Spring Data JPA repository 的 Save0) 方 法 将 其 保存 起 来 。 没 有 问题 ， 
我 们 只 需 调 用 Mono 的 block0) 方 法 惑 可 以 抽取 Taco 对 象 : 


tacoRepo.save(taco ) ; 
顾名思义 ，block(0) 方 法 会 执行 一 个 阻 团 操作 ， 完 成 数据 的 抽取 过 
如 来 要 从 Flux 中 抽取 数据 ， 我 们 可 以 使 用 tolIterable()。 假 设 我 们 有 


一 个 Flux<Taco>， 并 且 要 调用 Spring Data JPA repository 的 SaveAlH0) 方 
法 ， 如 下 的 代码 片段 将 从 Flux<Taco> 中 抽取 Iterable<Taco>: 


Iterable<Taco> tacos = tacoFlux.toIterable(); 
tacoRepo.saveAll(tacos); 


与 Mono.block() 类 似 ，Flux.tolterableO 在 将 Flux 发 布 的 对 象 抽 取 到 


Iterable 的 过 程 中 是 阻塞 的 。 因 为 它们 本 质 上 是 阻 才 的 ， 所 以 应 该 讶 慎 使 
用 Mono.block0 和 Flux.toIterable0， 并 且 要 清楚 地 认识 到 使 用 它们 会 打破 
反应 式 编程 模型 。 


要 避免 阻 暑 的 抽取 操作 ， 还 有 一 种 更 其 反应 式 的 方法 ， 束 是 订 册 
Mono 或 Flux， 并 在 其 及 布 每 个 元 又 的 时 候 执 行 所 需 的 操作 。 例 如 ， 要 
使 用 非 反 应 式 的 repository 你 存 Flux<Taco> 友 布 的 Taco 对 象 ， 我 们 可 以 这 
样 做 : 


tacoFlux.subscribe(taco -> { 
tacoRepo.save(taco ) ; 


}); 


虽然 调用 repository 的 save0) 方 法 依然 是 非 反 应 陈 的 阻 时 操作 ， 但 是 
在 消费 和 处 理 Flux 或 Mono 肥 布 的 数据 时 ， 使 用 subscribeO 十 一 种 更 目 
然 、 更 加 反应 去 的 方式 。 


天 于 非 反 应 式 repository， 我 们 已 经 讨论 得 够 多 了 。 接 下 来 ， 我 们 见 
识 一 下 Spring Data 反 应 式 功能 的 真正 威力 ， 为 Taco Cloud 应 用 创建 反应 


式 repository。 


12.1.3 ” 开 友 反应 式 repository 


正如 我 们 在 第 3 章 中 看 到 的 那样 ，Spring Data 最 令 人 赞叹 的 特性 之 
一 了 台 是 我 们 只 顷 声 明 repository 接 口 即 可 ， 在 运行 时 Spring Data 会 日 动 实 
现 它 们 。 在 那 一 章 中 ， 我 们 主要 天 注 Spring Data JPA， 但 是 同样 的 编程 
模型 也 适用 于 非 关 系数 据 库 ， 包 括 Cassandra 和 MongoDB。 


除了 Spring Data Cassandra 和 Spring Data MongoDB 对 非 反 应 式 
repository 的 文 持 之 外 ， 它 们 都 提供 了 反应 式 的 编程 模型 。 这 些 数 据 库 在 
后 问 提 供 数据 持久 化 芒 能 ，Spring 应 用 可 以 真正 实现 从 Web 层 到 数据 库 
的 站 到 痪 反应 陈 汪 。 我 们 首先 看 看 如 何 使 用 反应 式 Spring Data repository 
将 数据 持久 化 到 Cassandra。 


12.2 ”使 用 反应 式 的 Cassandra repository 


Cassandra 是 一 个 分 布 式 、 高 性 能 、 始 终 可 用 、 最 终 一 致 、 分 区 行 存 
储 的 NoSQL 数 据 库 。 


描述 该 数据 库 的 形容 词 是 非 钊 见长 的 ， 但 每 一 个 词 都 准确 说 明了 
Cassandra 的 威力 。 人 徐 而 言 之 ，Cassandra 处 理 的 是 数据 行 《row of 
data) ， 这 些 数据 行 会 在 多 个 分 布 式 市 上 中 分 区 。 不 会 有 任何 市 点 保存 
所 有 的 数据 ， 但 古 任何 给 定 的 行 痢 会 跨 多 个 市 护 你 和 存 副 本 ， 从 而 消除 了 
早点 故障 。 


Spring Data Cassandra 为 Cassandra 数 据 库 提供 了 目 动 化 repository 的 
文 持 ， 这 与 Spring Data JPA 为 天 系数 据 库 提 供 的 文 持 非常 相似 ， 但 又 有 
着 明显 的 差异 。 此 外 ，Spring Data Cassandra 还 提供 了 映射 注解 ， 用 于 将 
应 用 的 领域 闫 型 映射 到 文 返 的 数据 库 结 构 之 上 。 


在 我 们 进一步 探讨 Cassandra 之 前 ， 有 一 点 很 重要 ， 那 就 是 义 管 
Cassandra 与 关系 数据 库 (如 Oracle 和 SQL Server) 有 许多 相似 的 概念 ， 
但 Cassandra 并 不 是 关系 数据 库 ， 在 很 多 方面 与 天 系数 据 库 截然 人 不同。 我 


将 尝试 解释 Cassandra 的 独特 之 处 ， 因 为 这 与 如 何 使 用 Spring Data 有 关 。 
我 政 励 你 阅读 Cassandra 目 己 的 文档 ， 以 全 面 了 解 Cassandra 的 工作 原 
3s 


下 面 我 们 从 在 Taco Cloud 项 目 中 启用 Spring Data Cassandra 开 始 。 
12.2.1 司 用 Spring Data Cassandra 


要 开始 使 用 Spring Data Cassandra 的 反应 陈 repository 功 能 ， 我 们 需 
要 添加 反应 式 Spring Data Cassandra 的 Spring Boot starter 依 赖 。 实 际 上 ， 
我 们 可 以 从 两 个 Spring Data Cassandra starter 依 赖 间 进 行 选择 。 


如 条 不 打算 为 Cassandra 编 与 反应 取 repository， 那 么 我 们 可 以 在 构建 
文件 中 添加 如 下 依赖 : 


<dependency> 
<groupId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-data-cassandra</artifactId> 
</dependency> 





这 个 依赖 也 可 以 在 Initializr 中 通过 选中 Cassandra 复 选 框 添加 进来 。 


在 本 半 中 ， 我 们 主要 关注 编写 反应 式 repository， 所 以 需要 使 用 为 外 
一 个 文 持 反 应 式 Cassandra repository 的 starter 依 赖 : 


<dependency> 
<groupId>org.springframework.boot</groupId> 
<artifactId> 


spring-boot-starter-data-cassandra-reactive 
</artifactId> 
</dependency> 





如 果 使 用 Spring Initializr 创 建 项 目 ， 我 们 可 以 通过 选中 Reactive 
Cassandra 复 选 框 将 这 个 依赖 添加 到 构建 文件 中 。 


很 重要 的 一 点 在 于 ， 我 们 使 用 这 个 依赖 蔡 代 了 Spring Data JPA 
starter 依 顿 。 此 时 我 们 不 再 通过 JPA 将 数据 持久 化 到 关系 型 数据 库 中 ， 而 
是 使 用 Spring Data 将 数据 持久 化 到 Cassandra 数 据 库 中 。 因 此 ， 我 们 可 能 
想 要 从 构建 文件 中 移 除 Spring Data JPA starter 依 赖 和 关系 型 数据 库 的 依 
赖 〈( 如 JDBC 了 驱动 和 H2 依 赖 〉。 


Spring Data Reactive Cassandra starter 依 赖 会 为 项 目 引 入 多 个 依赖 
项 ， 其 中 包括 Spring Data Cassandra 库 和 Reactor。 由 于 这 些 库 位 于 运行 
时 类 路 人 径 中 ， 因 此 将 会 触发 创建 反应 式 Cassandra 库 的 目 动 配置 。 这 意味 
看 我 们 马上 残 能 开始 编写 反应 式 Cassandra repository， 而 无 纳 太 多 蛇 陈 
配置 。 


不 过 ， 少 量 的 配置 还 是 需要 的 ， 至 少 需 要 配置 键 空 间 (key Space ) 
时 名 称 ， 我 们 的 repository 要 在 该 键 空间 中 进行 操作 。 为 了 做 到 这 一 点 ， 
我 们 先 创 建 一 个 键 空间 。 


注意 : 在 Cassandra 中 ， 键 空间 是 Cassandra 节 点 中 的 一 组 





尽管 我 们 可 以 配置 Spring Data Cassandra 上 自动 创建 键 空 间 ， 但 是 手动 
创建 《或 使 用 现 有 的 键 空 间 ) 通 钊 要 容 多 得 多 。 便 助 Cassandra CQL 


(Cassandra Query Language，Cassandra 碍 询 语言 ) shell， 我 们 可 以 使 
用 如 下 的 create keyspace 命 令 为 Taco Cloud 应 用 创建 键 空间 : 


cqlsh> create keyspace tacocloud 


. With replication={'class':'SimpleStrategy', ‘replication factor':1} 
. and durable writes=true; 





简 而 言 之 ， 这 里 创建 了 一 个 名 为 tacocloud 的 键 空间 ， 并 且 使 用 简单 
条 上 略 的 复制 (replication〉 和 持久 性 写 入 (durable writes) 。 通 过 将 复制 
因子 设置 为 1， 我 们 硕 望 为 每 行 数据 保留 一 个 副本 。 复 制 全 略 决定 了 访 
如 何 处 理 复制 操作 。SimpleStrategy 复 制 策略 对 于 日 数据 中 心 《和 样 例 ) 
使 用 来 说 是 不 错 的 选择 ， 但 是 如 果 你 的 Cassandra 集 群 踊 多 个 数据 中 心 ， 
那 束 应 该 考虑 使 用 NetworkTopologyStrategy。 推 荐 你 阅读 一 下 Cassandra 
的 文档 ， 了 解 复制 打上 略 的 更 多 细 市 以 及 创建 键 空间 的 其 他 可 选项 。 


现在 ， 我 们 已 经 创建 了 键 空间 ， 接 下 来 应 该 配置 
spring.data.cassandra.keyspace-name 属 性 ， 告 诉 Spring Data Cassandra 诅 如 


何 使 用 该 键 空间 : 


spring: 


data: 
cassandra: 
Keyspace-name: tacocloud 
schema-action: recreate-drop-unused 





在 这 里 ， 我 们 将 spring.data.cassandra.schema-action 属 性 设置 为 
recreate-drop-unused。 这 项 配置 在 开 肥 阶段 非 营 有 用 ， 因 为 它 会 傈 证 应 
用 在 每 次 重新 局 动 的 时 候 ， 所 有 的 表 和 用 户 定 义 关 型 都 将 会 删除 并 重 
建 。 它 的 默认 值 为 none， 不 会 对 已 有 模 陈 采取 任何 操作 ， 在 生产 环境 


中 ， 这 种 设置 是 非常 有 用 的 ， 因 为 我 们 并 人 不想 在 应 用 局 动 的 时 候 删 除 所 
有 生产 环境 中 的 表 。 


在 本 地 运 Ne 我 们 只 需要 设置 这 两 个 属性 。 不 
， 除 了 这 两 个 属性 之 外 ， 你 可 能 还 想 要 设置 其 他 的 属性 ， 这 取决 于 你 
如 何 配置 Cassandra 集 和 群 。 


驮 认 情 况 下 ，Spring Data Cassandra 会 假定 Cassandra 在 本 地 运行 并 
监听 9092 端 口 。 如 果 事 实 并 非 如 此 ， 那 么 在 生产 环境 的 配置 中 我 们 可 能 


还 要 配置 Spring.data.cassandra.contact- points 和 spring.data.cassandra.port 属 
性 : 


Spring : 
data: 
cassandra: 
keyspace-name: tacocloud 


contact-points: 

- Casshost-1.tacocloud.com 
- Casshost-2.tacocloud.com 
- Casshost-3.tacocloud.com 
port: 9043 





注意 ，spring.data.cassandra.contact-points 属 性 是 我 们 识别 Cassandra 
主机 名 的 地 方 。 每 个 联系 点 (contact point) 代表 了 运行 Cassandra 闻 所 
的 主机 。 上 默认 情况 下 ， 它 会 被 设置 为 localhost， 但 是 我 们 可 以 将 其 设置 
为 主机 名 的 一 个 列表 。 应 用 会 答 试 连接 每 个 连接 点 ， 直 到 能 够 连接 上 其 
中 的 一 个 为 止 。 这 样 能 够 确保 在 Cassandra 和 集群 中 不 会 出 现 单 点 故障 ， 应 
用 能 够 通过 给 定 的 连接 点 与 集群 建立 连接 。 


我 们 可 能 还 需要 设置 Cassandra 集 群 的 用 户 名 和 黎 公 。 这 可 以 通过 设 


置 spring.data.cassandra.username 和 spring.data.cassandra.password 属 性 来 
实现 : 
Spring : 


data : 
cassandra: 


username: tacocloud 
password: s3cr3tP455werd 





现在 ， 在 我 们 的 项 目 中 已 经 局 用 和 配置 好 了 Spring Data Cassandra， 
接 下 来 瓯 应 该 将 领域 模型 与 Cassandra 表 进行 映射 并 编写 repository 了。 在 
此 之 前 ， 我 们 回 过 头 来 看 一 些 Cassandra 数 据 模型 的 基本 要 点 。 


12.2.2 ”理解 Cassandrab 的 数据 模型 


正如 表 文 所 述 ，Cassandra 与 关系 型 数据 库 有 很 大 的 不 同 。 在 将 领域 
类 型 映射 为 Cassandra 表 之 前 ， 理 解 Cassandra 数 据 模型 与 天 系 型 数据 库 
数据 持久 化 建 模 的 差异 是 非常 重要 的 。 


关于 Cassandra 数 据 模 型 ， 有 几 项 很 重要 的 事情 需要 理解 。 


。 Cassandra 表 可 能 有 任意 数量 的 列 ， 但 是 并 不 是 所 有 的 行 都 会 用 到 这 
= 

Cassandra 数 据 库 被 分 割 为 多 个 分 区 。 给 定 表 中 的 任何 一 行 部 可 以 由 
一 个 或 多 个 分 区 管理 ， 但 是 不 太 可 能 每 个 分 区 都 拥有 所 有 的 行 。 
Cassandra 表 有 两 种 键 : 分 区 键 (partition key) 和 集群 键 (clustering 
key) 。Cassandra 会 对 每 一 行 的 分 区 键 执行 哈 硕 操作 ， 以 确定 由 哪 
个 分 区 管理 该 行 。 集 群 键 决定 了 行 在 分 区 中 维护 的 顺序 〈 不 一 定 是 


它们 在 得 询 结束 中 出 现 的 顺序 ) 。 

。 Cassandra 对 读 操 作 进行 了 极 大 的 优化 。 因 此 ， 较 为 昭 见 和 推荐 的 做 
法 是 让 表 实 现 融 度 非 规范 化 ， 并 让 数据 器 多 个 表 进 行 复制 (比如 ， 
客户 信息 可 能 会 你 存在 customer 表 中 ， 同 时 也 会 复制 到 客户 所 创建 
的 订单 表 中 ) 。 


需要 说 明 一 点 ， 将 Taco Cloud 领 域 类 型 调整 为 使 用 Cassandra， 并 不 
是 简单 地 将 几 个 JPA 注 解 替 换 为 Cassandra 注 解 就 可 以 了 。 我 们 必须 重新 
考虑 如 何 对 数据 进行 建 模 。 


12.2.3 ”将 领域 对 象 有 映射 为 Cassandra 持 久 化 


在 第 3 章 中 ， 我 们 为 领域 类 型 (Taco、Ingredient、Order 等 ) 添加 了 
JPA 规 范 提 供 的 注解 。 这 些 注 解 会 将 领域 其 型 映射 为 要 持久 化 到 关系 型 
数据 库 中 的 实体 。 尽 窒 这 些 注 解 无 法 用 于 Cassandra 的 持久 化 ， 但 是 
Spring Data Cassandra 提 供 了 目 己 的 映射 注解 以 达到 同样 的 目的 。 


我 们 首先 从 Ingredient 开 始 ， 它 可 以 非 篆 容易 地 映射 到 Cassandra 
上 。 如 下 是 文 持 Cassandra 的 新 Imngredient 关 : 





package 七 acoSs ; 

import org.springframework.data.cassandra.core.mapping.PrimarykKey; 
import org.springframework.data.cassandra.core.mapping.Table; 
Import lombok.AccessLevel,; 

import lombok.Data; 

Import lombok.NoArgsConstructor.; 

Import lombok.RequiredArgsConstructor; 


@Data 

QRequiredArgsConstructor 
@QNoArgsConstructor(access=AccessLevel .PRIVATE, force=true) 
@Table("ingredients") 


public class Ingredient 1{ 


@PrimaryKey 

private final String id; 
private final String name; 
private final Type type; 


public static enum Type { 
WRAP, PROTEIN, VEGGIES, CHEESE, SAUCE 


} 





看 上 去 ，Ingredient 交 与 我 前 面 所 说 的 只 需 丛 换 几 个 注解 束 可 以 的 说 
法 相 政 盾 。 在 这 里 ， 我 们 不 再 使 用 JPA 持 久 化 中 的 @Entity 注 解 ， 而 是 使 
用 了 @Table 注 解 ， 这 表明 配料 将 会 持久 化 到 名 为 ingredients 的 表 中 。 田 
外 ， 我 们 不 再 为 id 属 性 使 用 @Id， 而 是 使 用 @PrimaryKey。 到 现在 为 
止 ， 我 们 似乎 只 是 瞧 换 了 几 个 注解 而 已 。 


但 是 ， 不 要 让 Ingredient 的 映 喘 砍 骗 了 你 。Ingredient 是 最 简单 的 领 
域 类 型 乙 一 。 如 果 我 们 将 Taco 类 进行 Cassandra 持 久 化 映射 〈 如 程序 清单 
12.1 所 示 ) ， 那 加 更 有 意思 了 。 


程序 清单 12.1 ”为 Taco 类 添加 注解 实现 Cassandra 持 久 化 





package tacos; 

import JjJava.util.Date,; 

import JjJava.util.List,; 

Import java.util.UUID; 

Import javax.validation.constraints.NotNull,; 

import Javax.validation.constraints.Size; 

Import org.springframework.data.cassandra.core.cql.Ordering; 
Import org.springframework.data.cassandra.core.cql.PrimaryKeyType; 
Import org.springframework.data.cassandra.core.mapping.Column,; 
Import org.springframework.data.cassandra.core.mapping.PrimaryKeyColumn; 
Import org.springframework.data.cassandra.core.mapping.Table; 
import org.springframework.data.rest.core.annotation.RestResource; 
Import com.datastax.driver.core.utils.UUIDs; 


Import Lombok .Data 


@Data 
@RestResource(rel="tacos", path="tacos") 
@Table("tacos") 一 --- 持久 化 到 tacos 表 
public class Taco { 

@PrimaryKeyColumn (type=PrimaryKeyType .PARTITIONED) 一 --- 定义 分 区 
键 


private UUID id = UUIDSs .timeBased(); 

@QNotNull 

@Size(min=5, message="Name must be at least 5 characters long") 

private String name ; 

@PrimaryKeyColumn(type=PrimaryKeyType .CLUSTERED, 一 --- 定义 集群 键 
ordering=Ordering.DESCENDING) 

private Date createdAt = new Date( ) ; 

@QSize(min=1, message="You must choose at least 1 ingredient") 

@QColumn("ingredients") 一 --- 将 列表 映射 到 in 


gredients 列 
private List<IngredientUDT> ingredients; 


我 们 可 以 看 到 ，Taco 类 的 映射 会 更 加 复杂 。 与 ngredient 类 似 ， 它 也 
使 用 @Table 注 解 声 明 taco 应 该 与 入 到 名 为 tacos 的 表 中 。 但 是 ， 这 是 它 与 
Ingredient 唯 一 的 相似 之 处 。 


id 属性 依然 是 主键 ， 但 它 只 是 两 个 主键 列 中 的 一 个 而 已 。 有 具体 来 
讲 ，id 属 性 使 用 了 @PrimaryKeyColumn 注 解 ， 并 且 type 的 值 为 
PrimaryKeyType.PARTITIONED。 这 表明 id 属性 要 作为 分 区 键 ， 用 来 确 
定 taco 数 据 的 每 一 行 要 写 入 到 哪个 分 区 中 。 


你 可 能 也 会 发 现 ，id 属 性 现在 是 UUID 类 型 ， 而 不 是 Long 类 型 。 虽 
然 不 是 强制 要 求 ， 但 是 保存 系统 生成 的 ID 值 的 属性 通常 是 UUID 类 型 


的 。 此 外 ， 针 对 新 Taco 对 象 ， 这 里 的 UUID 会 使 用 基于 时 间 的 UUID 进 行 
杞 始 化 《但 是 ， 从 数据 库 中 旋 取 已 有 Taco 时 ， 它 可 能 会 被 黎 新 ) 。 


我 们 继续 往 下 看 ，createdAt 属 性 映射 到 了 另外 一 个 主键 列 。 但 是 ， 
在 本 例 中 ，@PrimaryKeyColumn 的 type 属 性 设置 成 了 
PrimaryKeyType.CLUSTERED， 这 意味 着 createdAt 会 作为 集群 键 。 按 照 
前 文 所 述 ， 集 群 键 用 来 确定 行 在 集群 中 的 顺序 。 更 具体 来 讲 ， 我 们 将 顺 
序 设 置 为 降序 ， 所 以 ， 在 给 定 的 分 区 中 ， 较 新 的 行 会 优 移 出 现在 taco 表 
a 


最 后 ，ingredients 属 性 是 一 个 mmgredientUDT 对 象 的 List， 而 不 再 是 
Ingredient 对 象 的 List。Cassandra 表 是 高 度 非 规范 化 的 ， 因 此 可 能 会 包含 
与 其 他 表 重 复 的 数据 。 尽 管 ipPgredient 表 代表 了 上 所 有 可 用 配料 的 记录 ， 但 
是 taco 所 选择 的 配料 会 重复 保存 到 ingredients 列 中 。 我 们 不 会 简单 地 引用 
ingredients 表 中 的 一 行 或 多 行 ， 而 十 会 让 ingredients 属 性 包含 所 有 已 选 配 
料 的 完整 数据 。 


但 是 ， 我 们 为 什么 会 引入 新 的 mgredientUDT 类 呢 ? 为 何不 重用 
Ingredient 类 呢 ? 们 而 言 之 ， 包 含 数据 集合 的 列 ， 比 如 ingredients 列 ， 必 
须 是 原生 其 型 〈 束 型、 字符 串 等 ) 的 集合 或 用 户 定义 类 型 (user-defined 
type) 的 集合 。 


在 Cassandra 中 ， 用 户 定义 闫 型 能 够 让 我 们 声明 比 原 生 关 型 更 丰 遇 的 
表 的 列 。 通 第 ， 它 们 会 作为 天 系 型 结构 中 外 键 的 非 规范 化 模拟 形式 。 但 
是 ， 外 键 只 是 引用 为 外 一 张 表 中 的 一 行 数据 ， 与 之 不同， 用户 定义 类 型 


实际 上 会 持 有 其 他 表 中 某 行 数据 的 副本 。 在 tacos 表 的 ingredients 列 中 ， 
它 将 会 包含 配料 定义 的 数据 结构 集合 。 


我 们 不 能 将 Ingredient 用 作用 尸 定 义 尖 型 ， 因 为 @Table 注 解 已 经 将 
其 映射 成 了 Cassandra 中 的 一 个 持久 化 实体 。 所 以 ， 我 们 必须 创建 一 个 新 
的 类， 定义 该 如 何 将 配料 信息 存储 到 taco 表 的 ingredients 列 上 。 
IngredientUDT 类 (其 中 UDT 代 表 了 了 用户 定义 类 型 ， 即 user-defined type ) 
束 是 完成 这 项 工作 的 : 


package tacos; 


Import org.springframework.data.cassandra.core.mapping.UserDefinedType.; 


Import lombok.AccessLevel,; 

import lombok.Data; 

Import lombok.NoArgsConstructor:; 
Import lombok.RequiredArgsConstructor; 


@Data 

QRequiredArgsConstructor 
@QNoArgsConstructor(access=AccessLevel .PRIVATE, force=true) 
@QUserDefinedType("ingredient") 

public class IngredientUDT { 


private final String name; 
private final Ingredient.Type type; 





尺 官 IngredientUDT 和 Ingredient 看 上 去 非常 相似 ， 但 是 它 的 映射 需 
求 要 人 简单 得 多 。 它 使 用 了 @UserDefinedType 注 解 ， 表 明 这 是 Cassandra 中 
的 用 户 定 义 类 型 。 但 是 就 其 他 方面 来 讲 ， 它 束 是 有 几 个 属性 的 简单 类 。 


我 们 会 友 现 ，ImgredientUDT 关 没有 包 侣 id 属性 。 尽 管 它 也 可 以 包含 


源 Pngredient 中 id 属性 的 副本 ， 但 是 这 样 没 有 太 大 必要 。 实 际 上 ， 用 户 定 
义 类 型 可 以 包含 任何 想 要 的 属性 ， 它 没有 必要 与 表 定 义 一 一 对 应 。 


我 友 现 ， 可 视 化 用 户 定 义 关 型 与 表 中 的 持久 化 数据 之 间 的 关联 关系 
是 很 困难 的 。 图 12.1 展 现 了 整个 Taco Cloud 数 据 库 的 数据 模型 ， 包 含 了 
用 户 定义 类 型 。 


存储 在 “tacoorders" 表 中 
有 一 个 列表 
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图 12.1 ”在 这 里 不 再 使 用 外 键 和 连接 ，Cassandra 表 是 非 规范 化 的 ， 用 户 定义 类 型 包含 从 关联 表 
复制 的 数据 


具体 到 我 们 了 刚刚 创建 的 用 户 定义 类 型 ， 需 要 注意 Taco 有 一 个 
IngredientUDT 列 表 ， 其 中 包含 了 从 Ingredient 复制 而 来 的 数据 。 当 Taco 


持久 化 的 时 候 ，Taco 对 象 以 及 IngredientUDT 列表 都 会 持久 化 到 tacos 
表 中 。IngredientUDT 列 表 会 完整 地 持久 化 到 ingredients 列 中 。 


男 外 一 种 帮助 我 们 理解 用 户 定 义 类 型 如 何 使 用 的 办 法 就 是 从 数据 库 
中 查询 tacos 表 的 各 个 行 。 借 助 Cassandra 提 供 的 CQL 和 cglsh 工 上 共 ， 我 们 


可 以 看 到 如 下 的 结 来 : 


cqlsh:tacocloud> select id, name, createdAt, ingredients from tacos; 


| createdat | ingredients 


827396...| Carnivore | 2618-64...| [{name: 'Flour Tortilla', type: 'WRAP' 


}， 
{name: 'Carnitas', type: 'PROTEIN'}, 
{name: 'Sour Cream', type: “SAUCE 上 
{name: 'Salsa', type: 'SAUCE'}, 
{name: 'Cheddar', type: 'CHEESE'}| 





(1 rows) 


从 中 可 以 看 到 ，id、name 和 createdat 列 包含 的 都 是 简单 的 值 。 在 这 
方面 ， 它 们 与 关系 数据 库 的 类 似 查 询 天 别 不 大 。ingredients 列 整个 一 样 
了 ， 按 照 定义 ， 它 包含 用 户 定 义 的 ingredient 类 型 (由 IngredientUDT 所 
定义 ) 的 集合 ， 所 以 它 的 值 显 示 为 一 个 JSON 数 组 ， 数 组 中 则 是 JSON 对 
象 。 


你 可 能 也 注意 到 了 在 图 12.1 中 还 有 其 他 的 用 户 定 义 闫 型。 在 继续 将 
领域 对 象 映 射 为 Cassandra 的 过 程 中 ， 我 们 肯定 要 创建 更 多 的 用 户 定 义 关 
型 ， 其 中 包括 Order 类 所 用 到 的 类 型 。 程 序 清单 12.2 显 示 的 Order 类 ， 人 和 针 
对 Cassandra 持 久 化 进行 了 修改 。 


程序 清单 12.2 ”将 Order 类 映射 为 Cassandra tacoorders 表 





@Data 
@Table("tacoorders") 一 --- 有 映 映 到 tacoorders 表 
public class Order implements Serializable { 


private static final long serialVersionUID = 11; 


@PrimaryKey 一 --- 声明 主键 
private UUID id = UUIDSs .timeBased () ; 


private Date placedAt = new Date() ; 


QColumn("user'") 一 --- 映 冉 到 user 列 


private UserUDT user; 
// delivery and credit card properties omitted for brevity's sake 
@Column ("tacos") 一 --- 将 一 个 列表 映射 


到 tacos 列 
private List<TacoUDT> tacos = new ArrayList<>() 


public void addDesign(TacoUTD design) { 
this.tacos.add(design); 
} 





程序 清单 12.2 悬 省 略 了 Order 的 许多 属性 ， 这 些 属性 不 适合 
Cassandra 数 据 建 模 的 讨论 。 剩 下 的 属性 和 映射 方式 类 似 于 Taco 的 定义 。 
束 像 以 前 使 用 @Table 一 样 ， 在 这 里 @Table 用 于 将 Order 映 射 到 tacoorders 
表 。 在 本 例 中 ， 我 们 不 关注 顺序 ， 因 此 id 属性 只 使 用 了 @PrimaryKey 注 
解 ， 将 其 同时 作为 分 区 键 和 集群 键 ， 并 采用 了 默认 的 排序 。 


tacos 属 性 比较 有 趣 ， 因 为 它 是 List<TacoUDT>， 而 不 是 Taco 对 象 的 
列表 。 在 这 里 ，Order 和 Taco/TacoUDT 之 间 的 关系 类 似 于 前 文中 Taco 和 
Ingredient/IngredientUDT 之 间 的 关系。 也 束 是 说， 我 们 不 是 人 通过 外 刍 将 
不 同 表 中 的 多 行 数据 关联 在 一 起 ， 而 是 让 Order 表 包含 所 有 的 taco 数 据 ， 
以 便于 优化 未 的 快速 谈 取 。 


user 属 性 引用 了 UserUDT 对 象 ， 它 会 持久 化 到 user 列 中 。 
同样 ， 这 与 关系 型 数据 库 中 连接 另外 一 张 表 的 策略 是 不 同 的 。 


至 于 TacoUDT， 它 与 IngredientUDT 类 非常 相似 ， 不 过 它 里 面包 含 


了 对 万 外 一 个 用 户 定义 类 型 的 引用 : 


@Data 
QUserDefinedType("taco") 
public class TacoUDT { 


private final String name; 
private final List<IngredientUDT> ingredients; 





UserUDT 更 有 趣 一 点 ， 因 为 它 包 含 了 3 个 属性 ， 而 不 是 两 个 ; 


QUserDefinedType("user") 
@Data 
public class UserUDT { 


private final String Username ; 


private final String fullname,; 
private final String phoneNumber ; 





如 果 能 够 香 用 第 3 章 定 义 的 领域 尖 或 者 仅仅 将 全 A 注解 玲 换 为 
Cassandra 注 解 ， 那 当然 很 好 ， 但 是 Cassandra 持 久 化 的 本 质 特点 是 要 求 
我 们 重新 思考 数据 该 如 何 建 模 。 现 在 ， 我 们 已 经 映射 好 了 领域 模型 ， 接 
下 来 该 编写 repository 了。 


12.2.4 编 与 反应 式 Cassandra repository 
正如 我 们 在 第 3 章 所 看 到 的 ， 使 用 Spring Data 编 写 repository 只 需 声 


明 一 个 接口 ， 让 它 扩 展 Spring Data 的 基础 repository， 并 有 选择 性 地 声明 
用 于 目 定 义 但 询 的 方法 即 可 。 实 际 上 ， 编 写 肥 应 式 repository 并 没有 太 大 


的 不 同 。 主 要 区 别 在 于 ， 我 们 需要 扩展 一 个 不 同 的 基础 repository 接 口 ， 
而 且 我 们 的 方法 将 会 处 理 反 应 陈 发 布 者 ， 如 Mono 和 Flux， 而 不 再 是 领 
域 类 型 和 集合 。 


在 编写 反应 式 Cassandra repository 时 ， 我 们 有 两 个 基础 接口 可 选 : 
ReactiveCassandraRepository 和 ReactiveCrudRepository。 选 择 哪个 接口 很 
大 程度 上 取决 于 该 如 何 使 用 repository。ReactiveCassandraRepository 扩 展 
了 ReactiveCrudRepository， 提 供 了 insertO) 方 法 的 一 些 变种 ， 如 果 要 保存 
的 对 象 是 狐 建 的 ， 这 些 变 种 进行 了 优化 。 际 此 之 外 ， 
ReactiveCassandraRepository 提 供 了 与 ReactiveCrudRepository 相 同 的 操 
作 。 如 末 我 们 想 要 插入 很 多 数据 ， 那 么 可 能 需要 选择 
ReactiveCassandraRepository; 否则， 了 最 好 选择 ReactiveCrudRepository， 


因为 在 不 同 数据 库 类 型 之 间 它 更 具 可 移植 性 。 


Cassandra repository 必 须 是 反应 陈 的 吗 ? 


尽管 我 们 本 章 主要 天 注 如 何 使 用 Spring Data 编 与 反应 式 
repository， 但 是 你 可 能 想 知 道 该 如 何 为 Cassandra 编 写 非 反应 式 
的 repository。 如 果 是 这 样 ， 那 么 我 们 需要 让 repository 接 口 扩展 
非 反 应 式 的 CrudRepository 或 CassandraRepository 接 口 ， 而 不 是 扩 - 
展 ReactiveCrud Repository 或 ReactiveCassandraRepository。 我 们 
的 repository 方 法 就 可 以 返回 向 有 Cassandra 相 天 注解 的 领域 类 型 
或 这 些 领 域 类 型 的 集合 ， 而 不 再 是 Flux 和 Mono。 


如 果 你 准备 采用 非 反 应 式 的 repository， 那 么 可 以 将 starter 依 
赖 从 spring-boot- starter-data-cassandra-reactive 修 改 为 spring-boot- 


starter-data-cassandra, 不 过 这 并 不 是 严 格 要 求 的 o 





重新 看 一 下 我 们 为 Taco Cloud 编 写 的 repository， 要 使 它们 变 成 反应 
式 的 ， 我 们 首先 让 它们 扩展 ReactiveCrudRepository 或 
ReactiveCassandraRepository， 而 不 再 是 CrudRepository。 我 们 首先 看 一 
下 IngredientRepository。 除 了 使 用 配料 数据 初始 化 数据 库 之 外 ， 我 们 不 
会 插入 很 多 的 新 配料 数据 。 所 以 ，IngredientRepository 可 以 扩展 
ReactiveCrudRepository， 如 下 所 示 : 


public interface IngredientRepository 
extends ReactiveCrudRepository<Ingredient, String> { 


} 
我 们 不 需要 在 IngredientRepository 中 定义 任何 的 目 定义 但 询 ， 所 以 
要 将 IngredientRepository 变 成 反应 陈 repository， 并 不 需要 额外 的 工作 。 
现在 ， 它 扩展 了 ReactiveCrud Repository， 所 以 它 的 方法 处 理 的 都 是 Flux 
和 Mono。 例 如 ，findAll0 方 法 现在 返回 的 是 Flux<Ingredient>， 而 不 是 
Iterable<Ingredient>。 所 以 ， 在 使 用 它 的 时 候 ， 要 按照 正确 的 方式 来 使 
用 。 比 如 ，IngredientController 需 要 重 写 为 返回 Flux<Ingredient>: 


@GetMapping 
public Flux<Ingredient> allIngredients() { 


return repo.findAll(); 
} 





TacoRepository 的 变更 要 稍微 复杂 一 些 。 我 们 不 用 像 非 反 应 式 
repository 那 样 扩展 PagingAndSortingRepository， 而 是 可 以 扩展 
ReactiveCassandraRepository。 在 参数 化 Taco 对 象 的 时 候 ， 不 能 使 用 Long 
类型 的 ID 属性 ， 在 与 Taco 对 象 协作 的 时 候 ， 要 使 用 UUID 关 型 的 ID: 


public Interface TacoRepository 
extends ReactiveCrudRepository<Taco, UUID> 1{ 


} 


因为 这 个 新 TacoRepository 的 findAl10 方 法 会 返回 Flux<Ingredient>， 
所 以 我 们 不 用 让 它 扩 展 PagingAndSortingRepository， 也 不 用 操作 分 页 的 
数据 。 相 反 ， 在 DesignTacoController 的 recentTacos(0) 方 法 中 ， 我 们 只 需 
要 调用 返回 的 Flux 的 take0) 方 法 来 限制 要 消费 的 Taco 对 象 的 数量 即 可 〈 实 
际 上 ， 在 11.1.2 和 中， 我 们 已 经 修改 了 DesignTacoController 和 乞 的 
recentTacos() 方 法 ) 。 


OrderRepository 所 需 的 变更 也 很 简单 。 我 们 不 再 扩展 
CrudRepository， 人 向 是 让 它 扩展 ReactiveCassandraRepository: 


public interface OrderRepository 
extends ReactiveCassandraRepository<Order, UUID> { 


} 


最 后 ， 我 们 来 看 一 下 UserRepository。 我 们 可 能 还 记得 ， 
UserRepository 有 一 个 目 定义 的 查询 方法 ， 即 fmdByUsername()。 这 个 方 
法 让 定义 Cassandra 持 久 化 repository 有 了 一 些 变 化 。 支 持 Cassandra 的 
UserRepository 代 人 码 如 下 : 


public interface UserRepository | 


extends ReactiveCassandraRepository<User, UUID> { 


@AllowFiltering 
Mono<User> findByUsername(String username ) ; 





与 其 他 的 repository 接 口 〈 除 了 IngredientRepository ) 类 似 ， 
UserRepository 也 扩展 了 ReactiveCassandraRepository。 到 目前 为 止 ， 没 
有 感到 惊讶 的 地 方 。 但 是 ， 它 的 findByUsername0) 方 法 我 们 需要 注意 一 


首先 ， 因 为 这 是 一 个 反应 式 repository， 上 所 以 findByUsername0 不 会 
再 简单 地 返回 User 对 象 。 我 们 对 其 进行 了 重新 定义 ， 让 筷 返 回 
Mono<User>。 一 役 而 言 ， 在 反应 陈 repository 中 ， 我 们 目 定 义 的 得 询 方 
法 应 该 要 么 返回 Mono〈 要 返回 的 人 不 超过 一 个 ) ， 要 么 返回 Flux 会 
有 多 个 返回 值 ) 。 


同时 ， 按 照 Cassandra 的 特点 ， 在 得 询 表 的 时 候 ， 我 们 不 能 像 在 关系 
型 数据 库 的 SQL 中 那样 简单 地 使 用 where 子 句 。Cassandra 对 该 取 进 行 了 
优化 ， 但 是 使 用 where 子 名 进行 过 滤 可 能 会 拖 慢 其 他 快速 租 询 的 速度 。 
即便 如 此 ， 根 据 一 个 或 多 个 列 对 表 进 行 租 询 还 是 非常 有 用 的 。 因 此 ， 
@AllowFiltering 注 解 使 结 末 的 过 滤 变 成 了 现实 ， 它 可 以 作为 这 些 场景 的 
可 用 方案 。 


在 findByUsername() 中 ， 我 们 预期 的 CQL 但 询 如 下 所 示 : 


select * from users where Username= some Username  ; 


同样 ，Cassandra 十 不 允许 这 样 做 的 。 但 是 ， 在 将 @AllowFiltering 注 
解放 到 findByUsername0 方 法 上 之 后 ， 所 形成 的 CQL 奏 询 如 下 上 所 示 : 


select * from users where Username= Some username' allow filtering; 


但 询 末尾 的 allow filtering 子 句 提 醒 Cassandra， 我 们 已 经 意识 到 查询 
性 能 的 潜在 有 影响， 并 且 无 论 如 何者 需要 它 。 在 这 种 情况 下 ，Cassandra 将 
允许 使 用 where 子 句 并 按 需 过 滤 结 


Cassandra 中 有 很 多 强大 功能 ， 当 它 与 Spring Data 和 Reactor 结 合 使 用 
时 ， 我 们 可 以 在 Spring 应 用 中 到 分 使 用 这 些 功能 。 但 是， 让 我 们 把 注意 
力 转 移 到 支持 反应 式 repository 的 男 一 个 数据 库 上 来 ， 那 就 是 
MongoDB 。 


12.3 ”编写 及 应 式 的 MongoDB repository 


MongoDB 是 另 一 个 知名 的 NoSQL 数 据 库 。Cassandra 是 行 存 储 数据 
库 ， 而 MongoDB 则 被 视 为 文 梢 数据库。 更 具体 来 讲 ，MongoDB 以 
BSON (Binary JSON， 二 进 制 JSON ) 格式 存储 文档 ， 我 们 可 以 使 用 与 
伍 询 其 他 数据 库 中 的 数据 类 似 的 方式 合 询 和 检索 文档 。 


与 Cassandra 一 样 ， 必 须要 明确 知道 MongoDB 不 是 关系 数据 库 。 千 
理 MongoDB 服 务 右 集群 和 数据 建 模 的 方式 与 处 理 其 他 类 型 数据 库 时 的 
思维 方式 是 不 一 样 的 。 


不 过 ， 使 用 MongoDB 和 Spring Data 与 使 用 Spring Data 处 理 JPA 或 


Cassandra 并 没有 太 大 的 于 卉 。 我 们 会 在 人 岛 域 兴 上 使 用 注解 ， 将 领域 类型 
映射 为 文档 结构 。 我 们 还 会 编写 repository 接 口 ， 这 遵循 与 PA 和 
Cassandra 一 样 的 编程 模型 。 但 是 在 进行 任何 操作 之 前 ， 我 们 必须 在 项 目 
中 局 用 Spring Data MongoDB。 


12.3.1 局 用 Spring Data MongoDB 


要 局 用 Spring Data MongoDB， 我 们 需要 将 Spring Data MongoDB 
starter 深 加 a 到 项 目的 构建 文件 中 。Spring Data MongoDB 有 两 个 独立 的 可 


选 starter。 


如 果 你 使 用 非 反 应 式 的 MongoDB， 那 么 需要 将 如 下 的 依赖 添加 到 
构建 文件 中 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 
<artifactId> 


spring-boot-starter-data-mongodb 
</artifactId> 
</dependency> 





这 项 依赖 也 可 以 在 Spring Initializr 中 通过 选中 名 为 MongoDB 的 复 选 
框 添 加 进来 。 但 是 ， 本 章 主 要 天 注 的 是 编写 反应 陈 repository， 上 所 以 我 们 
要 选择 反应 式 Spring Data MongoDB starter 依 赖 : 

<dependency> 


<groupId>org.springframework.boot</groupId> 
<artifactId> 


spring-boot-starter-data-mongodb-reactive 
</artifactId> 
</dependency> 





在 Pitializr 中 ， 我 们 可 以 通过 选中 Reactive MongoDB 复 选 框 将 反应 
式 Spring Data MongoDB starter 添 加 进来 。 将 这 个 starter 沐 加 到 构建 文件 
中 之 后 ， 目 动 配置 功能 将 会 触发 ， 忆 用 Spring Data 对 目 动 化 repository 接 
口 的 文 持 ， 这 一 点 与 第 3 章 的 了 了 A 和 第 11 章 的 Cassandra 类 似 。 


驮 认 情 况 下 ，Spring Data MongoDB 会 假定 MongoDB 在 本 地 运行 并 
监听 27017 靖 口 。 为 了 测试 和 开 妥 的 便利 性 ， 我 们 可 以 选择 使 用 通 入 去 
的 Mongo 数 据 库 。 为 了 实现 这 一 点 ， 我 们 需要 将 Flapdoodle Embedded 
MongoDB 依 顿 球 加 到 构建 文件 中 : 


<dependency> 
<groupId>de.flapdoodle.embed</groupId> 


<artifactId>de.flapdoodle.embed.mongo</artifactId> 
</dependency> 





与 我 们 在 关系 型 数据 库 中 使 用 H2 类 似 ，Flapdoodle 艇 入 式 数 据 库 和 市 
来 了 使 用 内 存 Mongo 数 据 库 的 便利 性 。 也 束 是 说 ， 我 们 不 需要 运行 单独 
的 数据 库 ， 但 是 所 有 的 数据 会 在 应 用 重 司 的 时 候 丢 挥 。 


通 入 陈 数 据 库 对 于 开 有 友和 测试 是 很 不 销 鸭 ， 一 旦 我 们 将 应 用 部 普 到 
生产 环境 ， 束 需要 设置 儿 个 属性 ， 让 Spring Data MongoDB 知 道 访 问 何 
处 的 Mongo 数 据 库 以 及 该 如 何 进行 访问 : 

spring: 
data: 


mongodb: 
host: mongodb.tacocloud.com 


port: 270618 

Username: tacocloud 
password: s3cr3tp455werd 
database: tacoclouddb 





在 这 里 ， 并 不 是 所 有 的 属性 都 是 必需 的 。 如 条 Mongo 数 据 库 不 在 本 
地 运行 ， 那 么 这 些 属性 能 够 为 Spring Data MongoDB 指 明正 确 的 方向 。 
拆 分 一 下 上 面 的 配置 ， 如 下 吏 是 要 设置 的 每 个 属性 。 


spring.data.mongodb.host: Mongo 运 行 的 主机 名 〈 默 认为 
localhost) 。 

spring.data.mongodb.port: Mongo 服 务 右 监听 的 关口 (默认 为 
27017) 。 

spring.data.mongodb.username: 访问 安全 Mongo 数 据 库 的 用 户 名 。 
spring.data.mongodb.password: 访问 安全 Mongo 数 据 库 的 密码 。 
spring.data.mongodb.database: 数据 库 名 默认 为 test)。 


在 我 们 的 项 目 中 ， 己 经 启用 了 Spring Data MongoDB， 上 所 以 接 下 来 
我 们 需要 为 领域 对 象 添 加 注解 ， 以 便于 将 它们 持久 化 为 MongoDB 中 的 
文档 。 


12.3.2 ”将 领域 对 象 映 射 为 文档 


Spring Data MongoDB 提 供 了 多 个 注解 。 在 将 领域 对 象 映 射 为 要 持 
入 化 到 MongoDB 中 的 文档 结构 时 ， 这 些 注 解 是 非 铝 有 用 的 。 尽 管 Spring 
Data MongoDB 提 供 了 多 个 用 于 映射 的 注解 ， 但 是 其 中 的 3 个 是 最 沿用 
的 。 


。@Id: 将 菏 个 属性 指明 为 文档 的 ID 〈 来 目 Spring Data Commons) 。 

。 (@Document: 将 领域 类 型 声明 为 要 持久 化 到 MongoDB 中 的 文档 。 

。 (@Field: 指定 菜 个 属性 持久 化 到 文档 中 的 字段 名 称 〈《 以 及 可 选 的 顺 
Tu 


在 这 3 个 注解 中 ，@Id 和 @Document 是 严格 需要 的 。 除 非 显 式 指 
定 ， 人 否则 没有 使 用 @EField 注 解 的 属性 将 假定 字段 名 与 属性 名 相同 。 


将 这 些 注 解 应 用 到 Ingredient 类 上 的 效果 如 下 所 示 : 


package tacos; 

Import org.springframework.data.annotation.Id; 

import org.springframework.data.mongodb.core.mapping.Document; 
Import lombok.AccessLevel,; 

import lombok.Data; 

Import Lombok .NoArgsConstrFuctor ; 

Import lombok.RequiredArgsConstructor; 


@Data 

QRequiredArgsConstructor 
@QNoArgsConstructor(access=AccessLevel .PRIVATE, force=true) 
QDocument 


public class Ingredient 1{ 


@Id 

private final String id; 
private final String name; 
private final Type type; 


public static enum Type 1{ 
WRAP, PROTEIN, VEGGIES, CHEESE, SAUCE 


} 





可 以 看 人 到， 我 们 在 类 级 列 使 用 了 @Document 注 解 ， 表 明 Ingredient 古 
一 个 文档 实体 ， 可 以 在 Mongo 数 据 库 中 执行 读 取 和 写 入 操作 。 默 认 情 况 
下 ， 集 合 名 《这 是 Mongo 中 与 关系 型 数据 库 的 表 对 等 的 概念 ) 是 基于 类 
名 的 ， 只 不 过 第 一 个 字母 会 变 成 小 写 。 因 为 我 们 没有 特别 指定 ， 所 以 
EN 象 将 会 持久 化 到 名 ia 的 集合 中 。 但 是 ， 我 们 可 以 通 
过 设置 @Document 的 collection 属 性 改变 这 种 行为 : 


@Data 

QRequiredArgsConstructor 
@QNoArgsConstructor(access=AccessLevel .PRIVATE, force=true) 
QDocument(collection="ingredients") 

public class Ingredient 1{ 





我 们 还 会 看 到 ，id 属 性 使 用 了 @Id 注 解 。 这 表明 该 属性 将 会 作为 要 
持久 化 的 文档 的 ID 。 我 们 可 以 将 @Id 注 解 用 到 任意 Serializable 类 型 的 字 
段 上 上， 包括 String 和 Long。 在 本 例 中 ， 我 们 已 经 使 用 String 定 义 的 id 属性 
作为 日 然 标 识 从 ， 因 此 不 需要 将 其 更 改 为 其 他 类 型 。 


到 目前 为 止 ， 一 切 都 很 顺利 。 但 是 ， 不 要 忘 了 ， 在 本 章 前 面 的 内 容 
中 ， 我 们 兽 说 过 Ingredient 是 进行 Cassandra 了 映射 时 最 简单 的 一 个 领域 类 

型 。 其 他 的 闫 型 ， 比 如 Taco， 驳 稍微 困难 一 些 了 。 接 下 来 ， 我 们 看 一 下 
如 何 映 射 Taco 类 ， 看 看 它 会 有 哪些 恢 喜 。 


在 将 领域 其 型 映射 为 MongoDB 文 档 时 ， 我 们 肯定 需要 为 Taco 琴 加 
@Document 注 和 解 。 同 时 ， 我 们 还 需要 通过 @Id 注 解 指 定 ID 属 性 。 在 你 加 
完 文 持 MongoDB 持 久 化 的 注解 后 ， 我 们 就 会 得 到 如 下 的 Taco 类 : 





@Data 

@RestResource(rel="tacos", path="tacos") 
QDocument 

public class Taco 1{ 


@Id 
private String id; 


@QNotNull 
@Size(min=5, message="Name must be at least 5 characters long") 


private String name; 


private Date createdAt = new Date(); 


QSize(min=1, message="You must choose at least 1 ingredient") 
private List<Ingredient> ingredients; 





不 管 你 是 否 相 信 ， 这 束 是 上 所有 的 内 容 。 在 Cassandra 中 ， 我 们 还 需要 
处 理 两 个 不 同 的 主键 字段 并 且 要 引用 用 户 定 义 类 型 ， 但 这 是 Cassandra 特 
有 的 。 对 于 MongoDB 来 说 ，Taco 的 映射 要 人 窗 单 得 多 。 


即便 如 此 ， 在 Taco 中 还 是 有 一 些 有 意思 的 事情 值得 关注 。 首 先 ， 我 
们 要 注意 ，id 属 性 变 成 了 String 类 型 (而 不 是 JPA 版 本 中 的 Long 类 型 或 
Cassandra 版 本 中 的 UUID 类 型 〉。 正 如 我 在 前 文 所 述 ，@Id 注 解 可 以 用 
到 任意 Serializable 类 型 上 。 如 果 选 择 使 用 String 属 性 作为 ID， 我 们 就 可 
以 在 保存 的 时 候 让 Mongo 自 动 设 置 一 个 值 给 它 。 将 其 设置 为 String 类 型 
之 后 ， 我 们 残 得 到 了 一 个 数据 库 管 理 赋 值 的 ID， 而 不 用 再 担心 如 何 手动 
设置 该 属性 。 


我 们 再 看 一 下 ingredients 属 性 。 它 是 一 个 List<Ingredient>， 与 第 3 半 
中 的 JPA 版 本 非 第 类 似 。 与 JPA 版 本 不同 的 是 ， 这 个 列表 个 会 存储 到 单 
独 的 MongoDB 集 合 中 。 与 Cassandra 对 应 的 功能 类 似 ， 配 料 列表 会 直 
接 、 以 非 规 范 化 的 形式 存储 到 taco 文 档 中 。 不 过 ， 与 Cassandra 不 同 ， 我 
们 不 需要 创建 用 户 定义 类 型 ，MongoDB 非 党 乐意 使 用 任何 类 型 ， 不 管 
它 是 市 有 @Document 注 解 的 万 一 个 类 型 还 是 简单 的 POJO， 都 是 可 以 
的 。 


看 到 将 Taco 上 映射 为 文档 持久 化 非 营 容易 ， 我 们 可 以 松口 气 了 。 这 种 
了 映射 的 便利 性 会 延续 到 Order 领 域 闫 吗 ? 你 可 以 目 行 看 一 下 市 有 


MongoDB 注 解 的 Order 类 : 


@Data 
QDocument 
public class Order implements Serializable { 


private static final long serialVersionUID 


@Id 
private String id; 


private Date placedAt = new Date(); 


@Field("customer") 
private User USser ; 


// other properties omitted for brevity's sake 
private List<Taco> tacos = new ArrayList<>(); 


public void addDesign(Taco design) { 
this.tacos.add(design); 


} 





简单 起 见 ， 我 删除 了 投递 和 信用 卡 相关 的 各 种 字段 。 从 剩 下 的 部 分 
可 以 清楚 地 看 出 ， 与 其 他 领域 类 型 一 样 ， 我 们 只 需要 @Document 和 @Id 
注解 。 即 便 如 此 ， 我 们 也 为 user 属 性 使 用 了 @Field， 指 定 在 持久 化 文档 
中 它 将 会 存储 为 customer。 


User 领 域 关 的 MongoDB 持 久 化 映射 依然 非常 简单 ， 看 到 这 里 ， 相 信 
你 并 不 会 对 此 感到 意外 : 





@Data 

@QNoArgsConstructor(access=AccessLevel .PRIVATE, force=true) 
QRequiredArgsConstructor 

QDocument 

public class User implements UserDetails { 


private static final long serialVersionUID = 1L; 


@Id 

private String id; 

private final String username,; 
private final String password ; 
private final String fullname,; 
private final String street; 
private final String city; 
private final String state ; 
private final String zip; 

private final String phoneNumber ; 


// UserDetails method omitted for brevity's Sake 


虽然 有 一 些 更 高 级 和 不 遇见 的 场景 需要 额外 的 映射 ， 但 是 我 们 会 及 
现 ， 对 于 大 多 数 情况 ，@Document、@Id 以 及 偶尔 用 到 的 @Field 对 于 
MongoDB 映 里 来 说 已 经 四 够 了。 对 于 Taco Cloud 的 领域 类 型 ， 它 们 完全 
可 以 胜任 。 


剩 下 的 事情 就 是 编写 repository 接 口 了 。 
12.3.3 ”编写 反应 了 式 的 MongoDB repository 接 口 


Spring Data MongoDB 捉 供 的 目 动 化 repository 功 能 与 Spring Data JPA 
和 Spring Data Cassandra 关 似 。 在 为 MongoDB 编 写 反 应 却 repository 的 时 
保 ， 我 们 可 以 在 ReactiveCrudRepository 和 ReactiveMongoRepository 之 间 
进行 选择 。 核 心 的 差异 在 于 ，ReactiveMongoRepository 提 供 多 个 特殊 的 
insert(0) 方 法 ， 它 们 针对 新 文档 的 持久 化 进行 了 优化 ， 而 


ReactiveCrudRepository 依 顿 save0 方 法 来 保存 新 文档 和 已 有 的 文档 。 


如 何 编写 非 反 应 式 的 MongoDB repository ? 


本 章 主要 关注 如 何 使 用 Spring Data 编 写 反 应 式 的 repository。 
如 末 出 于 采种 原因 ， 你 希望 使 用 非 反 应 陈 的 repository， 那 么 可 以 
通过 让 repository 接 口 扩展 CrudRepository 或 MongoRepository 来 实 


现 ， 而 不 是 选择 扩展 ReactiveCrudRepository 或 ReactiveMongo 
Repository。 这 样 ， 我 们 融 可 以 让 repository 返 回 市 有 Mongo 注 解 
的 领域 类 型 或 这 些 领 域 类 型 的 集合 。 


尽 索 不 是 严格 要 求 的 ， 但 是 你 可 以 将 spring-boot-starter-data- 


mongodb-reactive 依 顿 将 换 为 Spring-boot-starter- data-mongodb。 





首先 ， 我 们 来 定义 将 ingredient 对 象 持久 化 为 文档 的 repository。 在 数 
据 库 初始 化 完成 之 后 ， 我 们 不 会 频 素 地 创建 配料 的 文档 ， 甚 至 有 可 能 永 
远 不 会 这 样 做 。 因 此 ，ReactiveMongoRepository 提 供 的 优化 没有 太 多 的 
用 处 ， 我 们 可 以 让 IngredientRepository 扩 展 ReactiveCrudRepository: 





package tacos.data; 
import org.springframework.data.repository.reactive.ReactiveCrudRepository 


2 
Import org.springframework.web.bind.annotation.CrossOrigin; 
import tacos.Ingredient,; 


QCrossOrigin(origins="*") 
public interface IngredientRepository 
extends ReactiveCrudRepository<Ingredient, String> { 


} 


稍 等 片刻 ! 它 看 起 来 与 我 们 在 12.2.4 小 节 中 为 Cassandra 编 写 的 
IngredientRepository 接 口 是 完全 一 样 的 ! 实际 上 ， 这 是 同一 个 接口 ， 没 
有 任何 变化 。 这 凸显 了 扩展 ReactiveCrudRepository 的 一 个 好 处 ， 也 就 是 
它 在 各 种 数据 库 类 型 之 间 上 其 有 更 强 的 可 移植 性 ， 并 且 针 对 MongoDB 和 
Cassandra 者 可 以 很 好 地 运行 。 


为 它 是 一 个 反应 式 repository， 所 以 它 的 方法 处 理 的 是 Flux 和 
Mono， 而 不 是 原始 领域 类 型 或 这 些 领 域 类 型 的 集合 。 例 如 ，findAl10) 方 
法 将 返回 Flux<Ingredient>， 而 不 是 Iterable<Ingredient>。 同 样 ， 
findByIdO 将 返回 Mono<Ingredient>， 而 不 是 Optional <Ingredient>。 
此 ， 这 个 反应 式 repository 可 以 作为 病 到 病 反 应 式 流 的 一 部 分 。 


现在 ， 为 了 将 Taco 持 久 化 为 MongoDB 中 的 文档 ， 我 们 定义 男 一 个 
repository。 与 配料 文档 不 同 ， 我 们 会 频 党 创建 taco 文 档 。 因 此 ， 
ReactiveMongoRepository 优 化 过 的 insertO0 方 法 束 很 有 价值 了 。 如 下 的 代 
侣 片段 展现 了 支持 MongoDB 的 TacoRepository 接 口 : 


package tacos.data; 
Import org.springframework.data.mongodb.repository.ReactiveMongoRepository 


2 
Import reactor.core.publisher.Flux; 
import tacos.Taco; 
public interface TacoRepository 
extends ReactiveMongoRepository<Taco, String> { 


Flux<Taco> findByOrderByCreatedAtDesc(); 





相对 于 ReactiveCrudRepository， 使 用 ReactiveMongoRepository 唯 一 


的 缺点 在 于 它 是 专属 于 MongoDB 的 ， 不 能 迁移 至 其 他 数据 库 。 在 你 的 
项 目 中 ， 你 需要 确定 这 种 代价 是 否 值 得 。 如 果 你 预计 不 会 在 某 个 时 刻 切 
换 到 不 同 的 数据 库 ， 那 么 尽 可 以 选择 ReactiveMongoRepository 并 充分 利 
用 它 针 对 数据 插入 操作 所 市 来 的 优化 。 


注意 ， 在 TacoRepository 中 ， 我 们 引入 了 一 个 新 的 方法 。 这 个 方法 
文 持 显示 了 最 近 创 建 的 taco。 在 JPA 上 拨 本 的 repository 中 ， 我 们 需要 通过 扩 
展 PagingAndSortingRepository 实 现 该 功能 。 但 是 ， 在 反应 式 repository 
中 ，PagingAndSortingRepository 并 没有 太 大 的 用 处 “尤其 是 分 页 功 
能 ) 。 在 Cassandra 版 本 中 ， 排 序 是 通过 表 定 义 中 的 集群 键 实现 的 ， 所 以 
在 repository 中 获取 最 近 创 建 的 taco 时 ， 我 们 并 不 需要 特殊 的 人 处理。 


对 于 MongoDB 来 说 ， 我 们 想 要 获取 了 最 近 创 建 的 taco。 尽 窒 名 字 看 上 
去 有 些 奇怪 ， 但 是 findByOrderByCreatedAtDesc(0) 方 法 遵循 上 自 定 义 查 询 方 
法 命名 约定 。 它 说 明 我 们 想 要 查找 Taco 对 象 ， 没 有 任何 查询 条 件 ， 我 们 
在 这 里 没有 设置 任何 必须 匹配 的 属性 。 然 后 ， 我 们 告诉 它 将 结束 按照 
createdAt 属 性 降序 排列 。 


在 这 里 ， 命 名 中 使 用 衬 By 子 句 的 原因 在 于 方法 名 称 中 还 有 另 一 个 
By， 这 样 做 可 以 避免 方法 名 称 出 现 误解 。 如 果 将 其 命名 为 
findAllOrderByCreatedAtDescO， 那 么 名 称 中 的 Allorder 部 分 将 家 忽略 ， 
Spring Data 将 尝试 通过 [匹配 createdAtDesc 属 性 来 查找 taco。 因 为 不 存在 
该 属性 ， 所 以 应 用 将 会 报销， 无 法 正 宙 局 动 。 


为 findByOrderByCreatedAtDescO 返 回 的 是 一 个 Flux<Taco>， 上 所 以 


我 们 不 用 担心 分 页 的 事情 。 相 反 ， 我 们 只 需要 使 用 take 操 作 获 取 Flux 友 
布 的 前 12 个 Taco 即 可 。 例 如 ， 在 显示 最 近 创 建 的 taco 的 控制 项 中 ， 我 们 
可 以 按照 如 下 方式 调用 findByOrderBy CreatedAtDesc(): 


Flux<Taco> recents = repo.findByOrderByCreatedAtDesc() 
.take(12); 


终 得 到 的 Flux 所 发 布 的 Taco 条 目 不 会 超过 12 个 。 


再 看 OrderRepository 接 口 ， 它 非常 简单 : 


package tacos.data; 
Import org.springframework.data.mongodb.repository.ReactiveMongoRepository 


2 
Import reactor.core.publisher.Flux; 
Import tacos.Order; 
public interface OrderRepository 
extends ReactiveMongoRepository<Order, String> 1{ 





我 们 会 频 澡 创建 Order 文 档 ， 有 所 以 OrderRepository 扩 展 了 
ReactiveMongoRepository， 从 而 充分 利用 其 insert0 方 法 所 市 来 的 优化 。 
除 此 之 外 ， 相 对 于 我 们 已 经 定义 的 repository， 它 并 没有 什么 新 奇 之 处 。 


最 后 ， 我 们 看 一 下 将 User 对 象 持久 化 为 文档 的 repository: 





package tacos .data; 
Import org.springframework.data.mongodb.repository.ReactiveMongoRepository 


2 
import reactor.core.publisher.Mono; 
import tacos.User; 


public interface UserRepository 
extends ReactiveMongoRepository<User, String> { 


Mono<User> findByUsername(String username ) ; 
} 


讲解 到 现在 ， 你 对 这 个 repository 接 口 应 该 没有 丝 坚 感到 尺 订 的 地 方 
了 。 与 其 他 repository 类 似 ， 它 扩展 了 ReactiveMongoRepository 〈 当 然 ， 
它 也 可 以 扩 nd 唯一 的 与 众人 不同 之 处 在 于 ， 它 
有 一 个 fndByUsername() 方 式 ， 这 是 在 第 4 章 中 我 们 为 了 文 持 认证 功能 添 
加 上 去 的 。 在 这 里 ， 将 它 修改 为 返回 Mono<User>， 而 不 是 原始 的 User 
对 象 。 


12.4 ”小结 


e。 Spring Data 文 持 为 Cassandra、MongoDB、Couchbase 和 Redis 数 据 库 
创建 反应 式 repository。 

e。 Spring Data 的 反应 式 repository 订 循 与 非 反 应 式 repository 相 同 的 编程 
模型 ， 只 不 过 它们 所 处 理 的 是 反应 式 发 布 者 ， 如 Flux 和 Mono。 

e。 非 反 应 式 repository 〈 比 如 JPA repository) 可 以 调整 为 使 用 Mono 和 
Flux， 但 是 在 体 存 和 获取 数据 时 它们 依然 是 阻塞 的 。 

。 在 使 用 非 关 系数 据 库 时 ， 需 要 理解 如 何 恰 当地 为 数据 建 模 ， 这 个 建 
模 过 程 决 定 了 数据 库 最 终 如 何 和 存储 数据 。 





[1] Spring Data R2DBC 致 力 于 解决 天 系 型 数据 库 的 反应 式 访 问 问题 。 
一 一 详 痢 注 


第 4 部 分 云 原生 Spring 


第 4 部 分 将 会 拆 分 单 体 应 用 模型 ， 我 们 会 介绍 Spring Cloud 和 微服 务 
的 开 肥 。 在 第 13 草 中 ， 人 简单 介绍 微服 务 之 后 ， 我 们 将 会 深入 介绍 服务 及 
现 ， 这 里 会 使 用 Spring 和 Netflix 的 Eureka 服 务 注册 中 心 实现 基于 Spring 的 
微服 务 的 注册 和 发 现 。 第 14 章 通过 Spring Cloud 的 Config Server 探 讨 中 心 
化 的 配置 ，Config Server 服 务 能 够 为 应 用 中 的 所 有 微服 务 提供 中 心 化 的 
配置 。 在 第 15 章 中 ， 我 们 将 会 借助 Netflix Hystrix 实 现 断 路 器 模式 ， 让 服 
务 面 对 失败 时 更 具 弹 性 。 


第 13 章 ”注册 和 发 现 服务 


。 思考 做 服务 


。 创建 服务 注册 中 心 


。 注册 和 友 现 服务 





你 看 过 《海底 总 动员 》 (Finding Nemo) 吗 ? 在 这 部 电影 中 ， 马 林 
(小 丑 鱼 ) 和 多 莉 《〈 监 唐 王 鱼 ) 试图 去 澳大利亚 悉尼 寻找 乌 林 失踪 的 儿 
子 尼 并 。 在 路 上 ， 它 们 过 到 了 一 和 群 翻车 鱼 。 为 了 好 玩 儿 ， 这 些 翻车 鱼 把 
目 己 摆 成 了 很 多 种 形状 一 一 全 位 、 八 眼 鱼 ， 它 们 甚至 还 授 成 马 林 的 样子 
来 模仿 它 。 当 多 莉 问 它们 是 含 知道 如 何 到 达 芒 尼 时 ， 它 们 组 成 了 悉尼 歌 
剧院 的 形状 ， 然 后 变 成 了 一 个 指 同 东 澳 大 利 亚 详 流 的 箭头 。 





虽然 这 部 电影 没有 深入 介绍 每 条 翻车 鱼 的 生活 ， 但 是 我 们 可 以 假定 
每 条 鱼 都 是 独立 于 其 他 翻车 鱼 的 个 体 。 它 们 都 有 目 己 的 鲜 片 、 鱼 、 鳃 、 
眼睛、 内 胜 ， 气 我们 所 知 ， 它 们 还 有 各 目的 布 望 和 梦想 。 尽 管 如 此 ， 写 


们 还 是 一 起 努力 形成 这 些 有 趣 的 形状 ， 帮 助 马 林 和 多 和 莉 前 往 澳 大 利 亚 。 


本 草 我 们 将 会 讨论 如 何 开 肥 翻车 鱼 所 组 成 的 应 用 程序 ， 这 是 一 系列 
章节 中 的 第 一 草 。 也 融 是 说 ， 你 将 会 看 到 如 何 使 用 和 做 服务 〈 一 些小 的 、 
独立 的 应 用 程序 ， 它 们 协同 工作 以 提供 完 整 应 用 的 功能 ) 进行 开 友 。 


更 具体 地 讲 ， 我 们 将 会 看 到 如 何 使 用 Spring Cloud 人 套件 中 一 些 最 有 
用 的 组 件 ， 包 括 配置 管理 、 容 销 以 及 本 章 的 主题 即 服务 及 现 。 但 是 ， 在 
此 之 前 ， 我 们 快速 、 整 体 地 了 人 解 一 下 使 用 微服 务 开 友 意味 看 什么 以 及 它 
们 能 够 提供 哪些 收 荔 。 


13.1 思考 微服 务 


到 目前 为 止 ， 我 们 都 是 将 Taco Cloud 开 发 为 单个 应 用 程序 ， 它 会 构 
建 为 一 个 可 部 普 的 JAR 或 WAR。 单 个 可 部 普 的 文件 似乎 是 一 种 很 目 然 的 
选择 。 毕 竟 ， 几 十 年 来 ， 大 多 数 的 应 用 程序 都 是 这 样 部 闭 的 。 即 便 可 能 
会 将 应 用 程序 拆 分 为 多 个 模块 进行 构建 ， 但 最 终 我 们 还 是 形成 一 个 JAR 
或 WAR， 并 将 其 投入 到 生产 环境 之 中 。 


在 构建 小 型 、 信 日 应 用 程序 的 时 候 ， 这 当然 是 显而易见 的 方式 。 有 有 
章 思 的 是 ， 小 型 应 用 程序 往往 会 不 断 增 长 。 当 需要 新 特性 的 时 候 ， 我 们 
能 够 轻而易举 地 同 项 目 中 添加 更 多 的 代码 。 在 我 们 发 觉 之 前 ， 它 已 经 变 
成 了 一 个 复杂 的 单 体 应 用 ， 甚 至 有 目 己 的 思想 。 残 像 电影 《小 彼 怪 》 
(Gremlins) 里 的 Mogwai 一 样 ， 如 果 你 一 直 别 它 ， 它 最 终 会 变 成 一 个 与 
你 作对 的 怪物 号 。 


单 体 应 用 看 似 简 单 ， 但 是 它 会 面临 各 种 挑 成 ， 如 下 所 示 。 


。 单 体 应 用 难以 理解 : 代码 库 越 大 ， 理 解 每 个 组 件 在 整个 应 用 程序 中 
所 担任 的 角色 就 越 困难 。 

。 单 体 应 用 难以 测试 : 随 看 应 用 的 不 断 增 长 ， 全 面 的 集成 和 验收 测试 

会 变 得 更 加 复杂 。 

单 体 应 用 更 容易 出 现 库 冲突 ， 实现 某 个 特性 所 需要 的 依赖 可 能 会 与 

其 他 特定 的 依赖 不 兼容 。 

单 体 应 用 的 扩展 较为 低 效 : 如 果 处 于 扩展 的 目的 要 将 应 用 程序 部 著 

到 更 多 的 便 件 上 ， 那 么 我 们 必须 要 将 整个 应 用 部 闭 到 更 多 的 服务 规 

上 ， 即 便 应 用 程序 中 很 小 的 一 部 分 需要 扩展 也 同样 如 此 。 

单 体 应 用 中 的 技术 决策 是 针对 整个 单 体 应 用 的 : 当 为 应 用 程序 选择 

语言 、 运 行 时 平台 、 框 架 和 库 的 时 候 ， 整 个 应 用 程序 都 会 遵循 我 们 

的 选择 ， 即 便 我 们 所 做 的 选择 只 是 为 了 文 持 茶 个 单独 的 用 户 场景 时 

同样 如 此 。 

单 体 应 用 需要 大 量 的 操作 过 程 才能 投入 生产 环境 : 当 应 用 程序 只 有 

一 个 部 普 单 元 时 ， 似 乎 更 容易 将 其 投入 生产 环境 。 事 实 上 并 非 如 

些 ， 单 体 应 用 程序 的 规模 和 复杂 性 通常 需要 更 严格 的 开发 过 程 和 更 

周全 的 测试 周期 ， 这 样 才 能 你 证 所 部 闭 的 应 用 程序 是 高 质量 的 ， 才 

能 避免 引入 bug。 


在 过 去 的 几 年 间 ， 敏 服务 架构 的 出 现 致 力 于 解决 这 些 挑 成 。 简 而 言 
之 ， 微 服务 架构 是 将 应 用 程序 分 解 为 可 独立 开 肥 和 部 垩 的 小 规模 、 微 型 
应 用 的 一 种 方式 。 这 些微 服务 之 间 互 相 协作 ， 以 实现 更 大 的 应 用 程序 的 
功能 。 与 单 体 应 用 程序 架构 相 比 ， 微 服务 如 构 有 以 下 特点 。 


。 和 伏 服务 易于 理解 : 每 个 微服 务 与 应 用 程序 的 其 他 微服 务 之 间 有 一 个 
很 小 且 有 限 的 九 约 。 因 此 ， 微 服务 更 加 专注 于 目标 ， 作 为 一 个 单 


元 ， 侯 服务 更 易于 理解 。 

做 服务 易于 测试 ， 事情 越 小 ， 融 越 便 于 测试 。 当 你 忠 若 单元 名 斌 、 
集成 测试 和 验收 测试 的 时 候 ， 这 一 点 非常 明显 。 它 也 适用 于 微服 务 
与 里 体 应 用 之 则 的 测试 。 

微服 务 较 少 受到 库 不 兼容 的 影响 : 因为 每 个 微服 务 都 有 目 己 的 构建 
依赖 项 的 集合 ， 而 这 些 依赖 项 不 会 与 其 他 的 微服 务 共 圣 ， 所 以 不 太 
可 能 会 出 现 库 冲突 的 现象 。 

微服 务 能 够 独立 扩展 : 如 条 指定 的 微服 务 需 要 更 多 的 处 理 能 力 ， 那 
么 内 存 分 配 和 /或 实例 数量 可 以 按 比 例 增 加 ， 而 不 会 影响 整体 应 用 
中 其 他 微服 务 的 内 存 和 实例 数量 。 

每 个 做 服务 可 以 选择 不 同 的 技术: 每 个 微服 务 可 以 选择 完全 不 同 的 
语言 、 平 台 、 框 架 和 库 。 实 际 上 ， 菏 个 使 用 Java 编 瑟 的 微服 务 与 砾 
一 个 使 用 C# 编 写 的 微服 务 进行 协作 是 完全 合理 的 外 。 

微服 务 可 以 更 加 频 索 地 有 友 布 到 生产 环境 中 : 尽管 微服 务 架 构 的 应 用 
征 由 许多 和 做 服务 组 成 的 ， 但 是 部 普 每 个 敏 服 务 的 时 候 ， 并 不 需要 其 
他 的 微服 务 都 已 经 部 普 殉 绪 。 而 且 ， 因 为 它们 更 小 、 更 集中 、 更 易 
于 测试 ， 所 以 将 微服 务 投 入 到 生产 环境 不 需要 那么 多 的 或 文 缠 市 。 
从 产生 想法 到 将 其 投入 生产 的 耗 时 可 以 用 分 钟 和 小 时 计量 ， 而 不 十 
用 周 和 月 。 


显然 ， 敏 服务 能 够 让 事情 变 得 更 简单 。 但 是 公平 地 讲 ， 微 服务 架构 
并 不 是 免费 的 午餐 。 敏 服务 淋 构 是 一 种 分 布 式 如 构 ， 有 目 己 需 要 应 对 的 
挑战 ， 包 括 网 络 延迟。 在 迁移 人 至 微服 务 淋 构 时 ， 我 们 需要 记 住 这 一 扣 ， 
因为 很 多 的 远程 调用 会 罕 积 并 降低 应 用 的 速度 。 


你 还 要 考虑 是 个 应 该 将 应 用 构建 为 微服 务 ， 因 为 并 不 是 所 有 的 应 用 
程序 都 需要 这 种 架构 ， 或 者 说 能 从 这 种 架构 中 受益 。 如 末 你 的 应 用 相对 
比较 小 或 者 比较 简单 ， 那 么 最 初 最 好 依然 床 用 单 体 架 构 。 随 着 它 的 不 断 


肥 展 ， 再 考虑 将 其 拆 分 为 微服 务 。 


在 开发 云 原生 、 微 服务 架构 的 应 用 时 ， 要 考虑 很 多 因 系 。 本 章 和 接 
下 来 的 几 章 主要 关注 Spring Cloud 所 提供 的 技术 ， 以 开发 由 微服 务 组 成 
的 应 用 程序 。 如 果 你 对 深入 研究 云 原生 应 用 程序 的 设计 和 思想 过 程 感 兴 
趣 ， 那 么 建议 阅读 Cornelia Davis 的 Cloud Native (Manning，2019) 。 


微服 务 染 构 所 面临 的 男 外 一 个 遇见 挑战 束 古 每 个 服务 该 如 何 知道 它 
要 协作 的 其 他 服务 在 哪里 。 这 恰好 是 本 章 的 主题 。 事 不 宜 迟 ， 我 们 马上 
看 一 下 如 何 使 用 Spring Cloud 搭 建 一 个 服务 注册 中 心 。 


13.2 搭建 服务 注册 中 心 


Spring Cloud 古 一 个 非常 大 的 爹 形 项 目 ， 由 多 个 独立 的 子 项 目 组 
成 ， 每 个 子 项 目 都 以 菏 种 形式 文 撑 看 微服 务 的 开发 。 其 中 有 一 个 子 项 目 
叫 作 Spring Cloud Netflix， 它 按照 Spring 的 编码 风格 重新 提供 了 Netflix 的 
多 个 组 件 。 在 这 些 组 件 中 包括 了 Netflix 的 服务 注册 中 心 Eureka。 


Eureka 艾 裸 裸 的 历史 真相 


Eureka 这 个 词 最 初 的 舍 义 是 当 人 们 找到 或 及 现 东 件 事 情 时 所 友 出 的 
欢呼 。 这 使 得 Eureka 非 常 适合 用 作 服 务 注册 中 心 的 名 称 ， 人 微服 务 要 信 助 
注册 中 心 实 现 彼此 友 现 的 功能 。 


据 传 说 ，Eureka 最 早 古 由 希腊 物理 学 家 阿 基 米 德 友 明 的 ， 他 举 在 浴 
于 里 的 时 候 友 现 了 浮力 的 原理 ， 于 是 他 跳出 浴 代 ， 炙 伦 神 地 跑 回 家 ， 嘴 


里 喊 着 “Eureka! ” 


关于 阿 基 米 德 是 否 真 的 光大 号 子 跑 回 家 并 大 喊 “Eureka! ”还 有 
争论 ， 但 无 论 如 何 ， 这 个 故事 非常 有 意思 


下 。 话 说 回来 ， 我 们 倒是 可 以 衣 
者 整洁 地 使 用 Eureka 服 务 注 册 中 心 。 


-一些 


ES 


人 


在 微服 务 应 用 中 ，Eureka 会 担当 所 有 服务 的 注册 中 心 。Eureka 本 号 
也 可 以 视 为 一 个 微服 务 ， 只 不 过 在 整体 应 用 中 它 的 目的 是 让 其 他 的 服务 
能 够 互相 发 现 。 


鉴于 它 在 微服 务 应 用 中 的 角色 ， 在 创建 需要 注册 的 服务 之 前 ， 我 们 
最 好 搭建 一 个 Eureka 服 务 注册 中 心 。 


, 为 了 理解 Eureka 的 运行 原理 ， 我 们 
可 以 参见 图 13.1 所 述 的 流动 过 程 。 


ra 


已 去 


当 服 务实 例 局 动 的 时 候 ， 


会 投 照 名 称 将 目 己 注册 到 Eureka 中 。 在 
图 13.1 中 ， 服 务 的 名 称 > 


some-service”。 “some-service”9J 


能 会 有 多 个 完 
全 等 价 的 实例 ， 但 是 在 Eureka 注 册 时 ， 它 们 的 名 称 是 相同 的 
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Netflix Eureka 
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选取 一 个 实例 并 消费 "some-service 的 端点 





“other-service” 





图 13.1 服务 使 用 Eureka 服 务 注册 中 心 进行 注册 这样 其 他 的 服务 束 能 发 现 并 消 颖 它们 了 了) 


在 某 个 时 间 点 ， 男 一 个 服务 (图 13.1 中 名 为 “other-service”) 需要 使 
用 “some-service” 的 端点 。 在 这 里 , “other-service” 没 有 使 用 特定 的 主机 
和 端口 信息 对 “some-service” 进 行 便 编码 ， 而 是 根据 名 字 从 Eureka 奉 
找 “some-service”。Eureka 的 回应 中 将 会 包含 它 所 知道 的 “some-service” 的 


所 有 实例 。 


现在 , “other-service” 需 要 做 决 案 。 生 坊 使 用 "some-service” 的 哪 
个 实例 昵 ? 如 果 它 们 都 是 完全 等 同 的 ， 其 实 束 没什么 天 系 了 。 为 了 避 斧 
每 次 都 选择 同一 个 实例 ， 最 好 用 一 些 客户 奖 负 载 平 衔 算 法 来 分 散 请 求 。 
这 束 是 Netflix 的 为 一 个 项 目 Ribbon 的 用 武之 地 了 。 


里 然 “other-service” 完 全 可 以 目 行 查找 和 选择 “some-service” 的 实 
例 ， 但 在 这 里 我 们 让 它 依 赖 Ribbon。Ribbon 是 一 个 客户 决 负载 平衡 右 ， 
会 帮助 “other-service” 做 出 选择 。Ribbon 做 完 选 择 之 后 ， 剩 下 的 就 是 
让 “other-service” 问 Ribbon 选 择 的 实例 发 出 请 求 。 


为 何 要 便 用 客户 闯 负 载 均 衡 华 


通 单 ， 我 们 会 认为 负载 均衡 希 是 一 个 中 心 化 的 服务 ， 它 处 理 所 有 的 
请 求 并 将 请 求 分 友 到 多 个 目标 实例 中 。 与 之 人 不同 ，Ribbon 是 一 个 客 刻 剖 
负载 均衡 大 ， 它 会 在 每 个 客户 问 上 友 起 请 求 。 


相对 于 中 心 化 的 负载 均衡 器 ，Ribbon 作 为 客户 端的 负载 均衡 器 会 有 
很 多 额外 的 收益 。 因 为 有 一 个 在 客户 器 本 地 的 负载 均衡 希 ， 所 以 负载 均 


衡 磺 能 够 很 目 袋 地 按照 客户 病 的 数量 成 比例 伸 。 此 外 ， 每 个 负载 均衡 
右 都 可 以 配置 成 最 适合 对 应 客户 站 的 负载 平衡 算法 ， 而 不 必 对 所 有 的 服 
务 都 使 用 相同 的 配置 。 


如 果 你 觉得 它 看 上 去 有 些 复 林 ， 那 么 不 用 担心 ， 随 后 我 们 束 会 看 到 
大 多 数 功 能 都 会 以 目 动 化 、 人 在 注册 和 消费 服务 
之 前 ， 我 们 需要 先 局 用 Eureka 服 务 


要 开始 使 用 Spring Cloud 和 Eureka， 我 们 需要 首先 为 Eureka 本 喘 创建 
一 个 全 新 的 项 目 。 最 简单 的 方式 是 使 用 Spring Initializr， 访 项目 可 以 使 
用 任何 名 称 ， 但 是 我 一 般 会 将 其 称 为 service-registry。 在 选择 starter 依 赖 
的 时 候 ， 我 们 只 需要 一 项 依赖 : 市 有 Eureka Server 标 和 俭 的 复 选 枉 。 在 创 
建 完 新 项 目 之 后 ， 在 Initializr 为 我 们 生成 的 项 目 中 ，pom.xml 将 会 包含 如 
下 依 颊 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-netflix-eureka-server</artifactId> 
</dependency> 





在 pom.xml 文 件 中 ， 我 们 还 可 以 看 到 名 为 spring-cloud.version 的 属性 
以 及 一 个 <dependencyManagement> 区 域 ， 它 们 指定 了 Spring Cloud 的 发 
布 版 本 。 当 我 创建 service-registry 的 时 候 ， 它 引用 的 是 Finchley train 的 第 
一 个 服务 友 布 版 本 (SR1) : 





<properties> 


<spring-cloud.version>Finchley.SR1</spring-cloud.version> 
</properties> 


<dependencyManagement> 
<dependencies> 
<dependency> 
<grouplId>org.springframework.cloud</groupId> 
<artifactId>spring-cloud-dependencies</artifactId> 
<version>${spring-cloud.version}</version> 
<type>pom</type> 
<scope>import</scope> 
</dependency> 
</dependencies> 
</dependencyManagement> 





如 果 你 想 要 使 用 不 同 版 本 的 Spring Cloud， 只 需要 将 Spring- 
cloud.version 属 性 修改 为 想 要 的 版 本 即 可 。 


在 构建 文件 中 添加 完 Eureka starter 依 赖 之 后 ， 要 局 用 Eureka 服 务 
伏 ， 我 们 还 需要 做 一 件 事 情 ， 那 束 是 打开 应 用 的 主 引 导 类 并 为 其 闵 加 
(@EnableEurekaServer 注 解 : 
@SpringBootApplication 


@EnableEurekaServer 
public class ServiceRegistryApplication { 


public static void main(String[] args) { 
SpringApplication.run(ServiceRegistryApplication.class, args); 





好 的 ， 这 样 束 可 以 了 ! 如 果 此 时 局 动 应 用 ，Eureka 服 务 注 册 中 心 碘 
会 运行 起 来 并 监听 8080 端 口 。 如 果 此 时 在 浏览 右上 访问 
http:Wlocalhost:8080， 将 会 看 到 如 图 13.2 所 示 的 Web 界 面 。 
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图 13.2 Eureka 基 于 Web 的 dashboard 


Eureka 的 dashboard 提 供 了 丰 训 的 信息 ， 它 会 告诉 我 们 都 有 哪些 服务 
实例 注册 在 Eureka 上 (当然 还 会 有 其 他 的 信息 ) 。 在 注册 服务 的 时 候 ， 
我 们 要 经 帅 访 问 这 个 UI 界 面 ， 确 体 它 们 鬼 照 预期 注册 了 进来 。 此 时 ， 还 
没有 服务 注册 ， 上 所 以 提示 信息 是 “No Instances Available”。 


Eureka 还 对 外 暴露 了 REST API， 借 助 它们 服务 可 以 日 行进 行 注 册 ， 
也 可 以 发 现 其 他 的 服务 。 你 可 能 不 会 直接 使 用 REST API， 但 是 你 会 发 
现 “/eureka/apps” 问 点 非常 有 意思 。 它 会 列 出 注册 中 心 所 有 服务 实例 的 细 


市 。 此 时 ， 我 们 没有 注册 任何 服务 ， 它 的 啊 应 如 下 所 示 。 在 注册 完 服 务 
之 后 ， 我 们 还 会 研究 这 个 症 所 : 


<applications> 
<versions delta>1l</versions delta> 


<apps hashcode></apps hashcode> 
</applications> 





你 会 友 现 ， 在 Eureka 的 日 志 中 ， 每 隔 大 约 30 秒 丈 会 打印 出 一 些 异 
名。 不 用 担心 ，Eureka 正 在 运行 ， 而 且 完全 符合 我 们 的 预期 。 但 十， 这 
些 寞 第 表明 我 们 还 没有 完全 配置 好 服务 注册 中 心 。 接 下 来 ， 我 们 湛 加 一 
些 配置 属性 来 消除 这 些 开 季 。 


13.2.1 配置 Eureka 


Eureka 不 喜欢 独 目 工作 ， 并 相信 数量 多 会 更 安全 的 理念 ， 升 望 能 够 
成 为 Eureka 服 务 器 集群 的 一 部 分 。 如 采 有 多 个 Eureka 服 务 左 ， 其 中 有 一 
个 过 到 问题 ， 束 不 会 出 现 单 点 故障 。 因 此 ，Eureka 的 默认 行为 是 与 其 他 
Fureka 服 务 夯 建立 关联 ， 符 试 获 取 其 他 Eureka 服 务 夯 的 服务 注册 中 心 ， 
甚 全 还 会 将 目 身 注册 为 其 他 Eureka 服 务 亏 的 服务 。 


在 生产 坏 境 中 ，Eureka 的 局 可 用 是 非常 有 价值 的 。 但 是 ， 对 于 开 友 
阶段 来 说 ， 局 动 多 个 Eureka 服 务 大 既 不 方便 也 没有 必要 。 为 了 达到 开 肥 
的 目的 ， 有 一 个 单独 的 Eureka 服 务 器 束 足 够 了 。 除 非 我 们 正确 配置 了 
Eureka 服 务 郝 ， 合 则 它 会 以 日 志文 件 中 开 篆 的 形式 每 隔 30 秘 殴 抱 优 抓 独 
状态 。 这 是 因为 ， 每 隔 30 秒 ，Eureka 服 务 器 就 会 尝试 与 男 外 的 Eureka 服 
务 占 建立 天 联 ， 以 注册 日 己 并 共 圣 其 注册 中 心中 的 信息 。 


我 们 需要 做 的 项 是 配置 Eureka 使 其 接受 当前 的 抓 独 状态 。 为 了 实现 
这 一 点 ， 我 们 需要 在 application.yml 中 设置 一 些 必 性， 代码 片段 如 下 所 


a 


和 仆 : 


eureka: 
instance: 
hostname: localhost 
client: 


fetch-registry: false 
register-with-eureka: false 
service-url: 
defaultZone: http://${eureka.instance.hostname}:${server.port}/eureka 





首先 ， 我 们 将 eureka.instance.hostname 属 性 设置 为 1ocalhost。 这 会 告 
诉 Eureka 它 正 运行 在 哪个 主机 (host) 上 。 这 个 属性 是 可 选 的 ， 如 果 我 
们 不 指定 它 ， 那 么 Eureka 会 答 试 通过 环境 变量 确定 它 的 主机 。 明 确 议 置 
这 个 属性 能 够 让 我 们 更 加 确定 它 的 值 。 


接 下 来 的 两 个 属性 是 eureka.client.fetch-registry 和 
eureka.client.register-with-eureka。 在 其 他 的 微服 务 中 ， 我 们 可 能 会 通过 
这 两 个 属性 告诉 它们 该 如 何 与 Eureka 服 务 器 进行 交互 。 但 是 ， 不 要 访 
了 ，Eureka 也 征 一 个 微服 务 ， 所 以 这 些 属性 也 可 以 用 到 Eureka 服 务 器 
上 ， 以 便于 告诉 它 该 如 何 与 其 他 Eureka 服 务 句 进行 交互 。 


这 两 个 属性 的 默认 值 都 是 true， 表 明 Eureka 应 该 从 其 他 的 Eureka 实 
例 获 取 注 册 人 信息， 并 且 应 议 将 上 和 目 号 注 册 为 其 他 Eureka 服 务 器 中 的 服务 。 
因为 在 开发 模式 下 并 没有 其 他 的 Eureka 服 务 器 ， 所 以 我 们 将 它们 设置 为 
false， 这 样 Eureka 将 不 会 答 试 与 其 他 的 Eureka 服 务 器 建立 关联 。 


最 后 ， 我 们 还 设置 了 eureka.client.service-url 属 性 。 这 个 属性 包含 了 
Zone 名 称 与 该 Zone 下 一 个 或 多 个 Eureka 服 务 左 之 间 的 映射 天 系 。 
defaultZone 十 一 个 特殊 的 key， 如 采 客 户 姗 《在 本 例 中 ， 也 下定 Eureka 本 
身 ) 没有 指定 所 需 的 zone， 束 将 会 使 用 这 个 zone。 因 为 我 们 只 有 一 个 
Eureka， 瞻 射 到 默认 zone 的 URL 束 是 Eureka 服 务 大 本 号 ， 所 以 这 里 使 用 
了 占 位 符 变 量 ， 由 其 他 属性 质 苑 它 的 信 。 


指定 Eureka 的 服务 需 瘦 口 


尽管 不 一 定 是 强制 要 求 ， 但 是 我 们 可 能 想 要 修改 默认 的 服务 器 姗 
中 。 里 然 Eureka 非 常 乐意 监 昕 8080 尊 口 ， 但 是 在 开发 代码 的 时 候 我 们 可 
能 会 在 本 地 机 和 需 同 时 运行 多 个 应 用 《微服 务 ) ， 也 就 无 法 让 所 有 的 应 用 
均 监 听 8080 痪 口 。 因 此 ， 在 本 地 开 肥 的 时 候 ， 设 置 server.port 属 性 通 闻 
是 一 个 比较 好 的 做 法 : 


server: 
port: 8761 
在 这 里 ， 我 们 将 端口 设置 成 了 8761， 这 是 Eureka 客 户 端 (我 们 将 会 
在 13.3 节 中 进行 讨论 ) 默认 监听 的 端口 。 
莹 用 目 我 你 护 模 陈 


另外 一 个 我 们 需要 考虑 设置 的 属性 是 eureka.server.enable-self- 
preservation。 如 有 果 我 们 局 动 Eureka 服 务 天 并 让 它 空 亲 一 分 钟 以 上 ， 可 能 
束 会 在 Eureka UI 上 看 到 一 个 非常 吓人 的 错误 信息 ， 如 图 13.3 所 示 。 


©) spring rt 





System Status 





Environment test Current time 2018-04-15T17:17:51 -0600 





Data center default Uptime 00:22 


RENEWALS ARE LESSER THAN THE THRESHOLD. THE SELF PRESERVATION MODE IS TURNED 
OFF.THIS MAY NOT PROTECT INSTANCE EXPIRY IN CASE OF NETWORK/OTHER PROBLEMS. 


图 13.3 在 目 我 保护 模式 下 ，Eureka 会 在 dashboard 显 示 信 息 


尽 管 这 里 使 用 了 红色 字体 和 大 与 字母 ， 但 是 这 条 信息 并 不 像 看 上 去 
那么 严重 。Eureka 和 希望 服务 实例 能 够 注册 上 来 ， 并 且 每 隔 30 秒 回 它 发 送 
一 次 注册 更 新 的 请 求 。 通 常 ， 如 果 Eureka 在 3 个 更 新 半期 (或 者 说 90 
秒 ) 内 没有 收 到 服务 的 更 新 请 求 ， 束 会 将 该 服务 注销 。 在 本 例 中 ， 
Eureka 假 定 出 现 了 网 络 问 题 ， 进 入 目 我 保护 模式 ， 所 以 不 会 注销 服务 实 
例 。 


在 生产 环境 中 ， 目 我 体 护 模式 是 很 好 的 ， 可 以 防止 在 出 现 网 络 故障 
时 更 新 请 求 无 法 肥大 全 Eureka 所 导致 的 活跃 服务 被 和 注销。 但 是 ， 在 我 们 
第 一 次 局 动 Eureka 并 且 还 没有 注册 任何 服务 时 候 ， 出 现 这 样 的 告警 会 让 
人 产生 疑虑 。 我 们 可 以 将 eureka.server.enable-self- preservation 属 性 设置 
为 false， 从 而 茶 用 目 我 保护 模 陈 : 


eureka: 


server: 
enable-self-preservation: false 





这 个 属性 在 开 友 坏 境 中 是 非 弟 有 用 的 。 在 开 友 环境 中 ， 基 于 各 种 原 


央 ，Eureka 可 能 会 收 不 到 更 狐 请 求 。 在 这 种 环境 下 ， 我 们 可 能 会 频繁 地 
司 动 或 关 财 服务 实例 ， 目 我 保护 模式 会 将 已 停止 服务 的 注册 项 体 留 下 
来 ， 故 一 个 服务 访问 已 经 不 可 用 的 服务 时 就 会 产生 问题 。 禁 用 卓 动 保护 
模式 将 会 防止 这 种 诡异 的 问题 。 然 和 而， 我们 付出 的 代价 就 是 会 看 到 另 一 
条 恐怖 的 红色 信息 〈 见 图 13.4) 。 


THE SELF PRESERVATION MODE IS TURNED OFF.THIS MAY NOT PROTECT INSTANCE EXPIRY IN CASE 
OF NETWORK/OTHER PROBLEMS. 


图 13.4 ”禁用 自我 保护 模式 时 ， 提 示 自 我 保护 模式 已 禁用 
虽然 我 们 在 开发 环境 可 以 禁用 自我 保护 模式 ， 但 是 在 投入 生产 环境 
时 需要 将 其 司 用 。 


13.2.2 ”扩展 Eureka 


在 开发 环境 中 ， 单 个 Eureka 实 例会 更 加 便利 ; 但 是 在 将 应 用 投入 生 
产 环 境 时 ， 我 们 可 能 至少 需要 两 个 Eureka 实 例 ， 以 实现 高 可 用 性 。 


生产 环境 可 用 的 Spring Cloud Services 


在 将 微服 务 部 普 到 生产 环境 时 ， 有 许多 需要 考虑 的 因 系 。Eureka 的 
局 可 用 性 和 安全 性 在 开发 阶段 可 能 并 不 太 重 要 ， 但 是 在 生产 环境 中 束 非 
常 关 键 了 。 如 果 你 是 Pivotal Cloud Foundry 或 Pivotal Web Services 的 客 
尸 ， 束 可 以 让 他 们 来 关心 这 些 事情 了 。 


Spring Cloud Services 提 供 了 一 个 Eureka 实 现 ， 同 时 还 包含 了 配置 服 
务 左 和 断路 硕 dashboard。 我 们 所 需要 做 的 陨 是 从 marketplace 请 求 一 个 p- 


Service-registry 服 务 ， 然 后 将 目 己 的 微服 务 绑 定 到 该 服务 上 。 在 
marketplace 中 ， 配 置 服务 左 和 断路 左 dashboard〈 我 们 将 会 在 接 下 来 的 两 
划 中 讨论 它们 〉 的 名 称 分别 为 p-config-server 和 Pp-circuit-breaker- 
dashboard 。 


配置 两 个 (或 更 多 ) Eureka 实 例 最 人 简 持 直接 的 方式 就 是 在 
application.yml 中 使 用 Spring profile， 然 后 针对 两 个 profile 各 局 动 一 次 。 
例如 ， 程 序 清单 13.1 中 的 配置 项 会 将 爽 个 Eureka 服 务 夯 设置 为 彼此 对 等 
的 病 。 


程序 清单 13.1 使 用 Spring profile 将 Eureka 配 置 成 两 个 对 等 的 端 


eureka: 
client: 
service-url: 
defaultZone: http://${other.eureka.host}:${other.eureka.port}/eureka 


spring: 
profiles: eureka-1 
application: 
name: eureka-1 


server: 
port: 8761 


eureka: 
instance: 
hostname: eurekal1.tacocloud.com 


other: 
eureka: 
host: eureka2.tacocloud.com 
port: 8761 


spring: 
profiles: eureka-2 


application: 
name: eureka-2 


server: 
port: 8762 


eureka: 
instance: 
hostname: eureka2.tacocloud.com 


other: 
eureka: 
host: eurekal.tacocloud.com 
port: 8762 





在 默认 的 profile 中 〈 位 于 程序 清单 13.1 顶 部 ) ， 我 们 用 占 位 和 从 变量 
来 设置 eureka.client. service-url.defaultZone 属 性 ， 这 些 占 位 符 都 是 在 每 个 
profile 特 定 的 配置 中 设置 的 。 


在 默认 的 profile 之 后 ， 我 们 配置 了 两 个 profile， 分 别 为 eureka-1 和 
eureka-2。 每 个 profile 都 按照 上 自己 的 配置 需要 指定 了 端口 和 
eureka.instance.hostname。 随 后 ， 我 们 设置 了 两 个 略 显 替 强 的 
other.eureka.host 和 other.eureka.port 属 性 ， 在 每 个 profile 中 它们 都 指向 了 
其 他 的 Eureka 实 例 。 这 两 个 属性 与 框架 本 里 是 没有 关系 的 ， 但 是 在 默认 
profile 的 占 位 和 从 中 会 引用 它们 。 


注意 ， 我 们 在 这 里 没有 设置 eureka.client.fetch-registry 或 
eureka.client.register-with-eureka。 它 们 的 默认 值 为 true， 因 此 能 够 确保 每 
个 Eureka 服 务 亏 都 会 问 对 方 进行 注册 ， 并 且 能 够 从 其 他 Eureka 服 务 磺 上 
获取 注册 信息 。 


目前 ，Eureka 服 务 注 册 中 心 已 经 局 动 并 处 于 运行 状态 了 。 但 是 ， 它 


现在 就 像 一 个 没有 人 查阅 的 空 电 话 本 。 只 有 让 服务 开始 在 注册 中 心 注 
册 ， 并 让 其 他 服务 查找 和 调用 它们 才 行 ， 人 否则 我 们 的 工作 都 是 徒 萝 的 。 
接 下 来 ， 我 们 看 一 下 如 何 让 微服 务 成 为 Eureka 的 客户 首 。 


13.3 注册 和 人 发现 服 务 


没有 服务 注册 的 话 ，Eureka 服 务 注 册 中 心 没有 任何 用 处 。 如 末 你 的 
服务 想 要 被 其 他 服务 友 现 和 消 颖 ， 丈 需要 将 它们 作为 服务 注册 中 心 的 客 
性 轿 。 为 了 让 应 用 任何 应 用 ,但 很 可 能 是 微服 务 〉 成 为 服务 注册 中 心 
的 各 户 背 ， 我 们 全 少 需要 将 Eureka 各 户 奖 依赖 诊 加 到 服务 应 用 的 构建 文 
11 本 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId> 
</dependency> 





与 Eureka 服 务 堪 starter 依 赖 类 似 ， 我 们 还 需要 为 Spring Cloud 的 依赖 
管理 设置 Spring Cloud 的 版 本 属性 : 





<properties> 


<spring-cloud.version>Finchley.SR1</spring-cloud.version> 
</properties> 


<dependencyManagement> 
<dependencies> 
<dependency> 
<grouplId>org.springframework.cloud</groupId> 
<artifactId>spring-cloud-dependencies</artifactId> 
<version>${spring-cloud.version}</version> 
<type>pom</type> 


<scope>import</scope> 
</dependency> 
</dependencies> 
</dependencyManagement> 


我 们 可 以 手动 添加 这 些 条 目 到 服务 应 用 的 pom.xml 文 件 中 ， 但 是 更 
简单 的 方式 是 在 Spring Initializr 的 复 选 杠 中 选中 Eureka Discovery 依 赖 。 


Eureka client starter 依 顿 会 添加 通过 Eureka 友 现 服务 所 需 的 所 有 内 
容 ， 包 括 Eureka 的 客户 问 库 以 及 Ribbon 负 载 均衡 左 。 我 们 只 需要 将 这 个 
依赖 添加 进来 ， 束 能 将 应 用 变 成 Eureka 服 务 注 册 中 心 的 客户 端 。 当 应 用 
局 动 的 时 候 ， 它 会 答 试 联系 在 本 地 运行 并 且 冰 口 为 8761 的 Eureka 服 务 
器 ， 并 将 自身 基于 UNKNOWN 名 称 进行 注册 。 


13.3.1 配置 Eureka 客 户 端 属性 


对 于 开发 阶段 来 说 ， 默 认 位 置 的 Eureka 服 务 器 是 可 以 接受 的 ， 如 果 
我 们 要 将 服务 部 着 到 localhost 之 外 ， 残 需要 履 兰 它 的 仁 。 另 外 ， 默 认 的 
服务 名 为 UNKNOWN， 这 是 一 个 非 营 粳 糕 的 选择 .…… 但 是 ， 坦 日 来 
讲 ， 任 何 形 陈 的 称 认 方案 都 会 很 炬 糕 ， 因 为 如 采 采 用 默认 方案 ， 那 么 所 
有 服务 都 会 具有 相同 的 名 称 。 


更 改 服 务 在 Eureka 中 的 注册 名 称 非 第 稍 单 ， 我 们 只 需要 设置 
spring.application.name 属 性 就 可 以 了 。 例 如 ， 如 果 想 要 注册 一 个 处 理 
taco 配 料 相 关 操 作 的 服务 ， 那 么 我 们 可 以 将 其 注册 为 ingredient-service。 
在 application.yml 中 ， 将 会 如 下 所 示 : 


Spring : 


application: 
name: ingredient-service 





设置 完 这 个 属性 之 后 ， 我 们 束 可 以 按照 ingredient-service 名 称 来 查 
找 服 务 了 。 另 外 ， 如 末 我 们 为 配料 服务 汪 加 多 个 实例 ， 筷 们 融会 以 相同 
的 名 称 出 现在 注册 中 心 ， 实 际 上 ， 服 务 会 扩展 到 多 个 实例 ， 并 假定 它们 
征 完 全 相同 的 ， 服 务 的 消费 者 可 以 从 中 选择 。 此 时 ， 我 们 得 看 Eureka 
dashboard 的 话 ， 服 务 将 会 如 图 13.5 所 示 。 


Instances currently registered with Eureka 





INGREDIENT-SERVICE n/a (1) (1) UP (1) - 192.168.1.3:ingredient-service 


图 13.5 ”Eureka dashboard 上 的 配料 服务 


在 继续 使 用 Spring Cloud 的 过 程 中 ， 你 会 发 现 spring.application.name 
是 我 们 要 设置 的 最 重要 的 属性 之 一 。 它 决定 了 Eureka 中 的 注册 名 。 在 第 
14 章 中 我 们 将 会 看 到 ， 这 个 属性 会 帮助 配置 服务 识 询 该 应 用 ， 用 来 管理 
特定 应 用 的 配置 。 其 他 的 Spring Cloud 项 目 ， 如 Spring Cloud Task〈 短 暂 
存活 的 微服 务 ) 和 Spring Cloud Sleuth 〈 分 布 式 跟踪 ) ， 同 样 依赖 
spring.application.name 属 性 来 识别 服务 。 


正如 我 们 在 第 1 章 所 学 到 的 ， 默 认 情 况 下 ， 所 有 的 Spring MVC 和 
Spring WebFlux 应 用 都 会 监听 8080 端 口 。 因 为 这 些 服务 现在 只 会 通过 
Eureka 进 行 得 找 ， 所 以 它们 监听 什么 关口 也 束 无 所 谓 了 ，Eureka 能 鹃 知 
道 它们 使 用 的 是 什么 闹 口 。 为 了 避免 本 地 运行 时 潜在 的 新 口 冲 突 ， 我 们 
可 以 将 端口 设置 为 0: 


server: 
port: 6 


注意 : 将 端口 设 普 成 0 的 话 ， 应 用 会 选择 任意 一 个 可 用 病 口 


来 局 动 。 





现在 ， 我 们 要 考虑 Eureka 服 务 右 的 位 置 。 默 认 情 况 下 ，Eureka 各 户 
端 会 假定 Eureka 服 务 器 在 本 地 运行 《8761 端 口 ) 。 对 于 开发 期 来 次 ， 这 
种 方式 很 不 铺 ， 但 是 在 生产 环境 中 ， 关 多 数 情况 并 非 如 此 。 因 此 ， 我 们 
需要 指定 Eureka 服 务 器 的 位 置 。 这 与 Eureka 服 务 噩 本 喘 的 实现 方式 完全 
相同 ， 都 是 要 使 用 eureka.client.service-url 必 性 : 


eureka: 
client: 


service-url: 
defaultZone: http://eurekal.tacocloud.com:8761/eureka/ 





通过 这 样 的 配置 ， 客 户 端 会 使 用 eurekal.tacocloud.com 主 机 (端口 
8761) 上 的 Eureka 服 务 右 进行 注册 。 只 要 Eureka 服 务 需 在 运行 ， 这 种 方 
式 束 是 没有 问题 的 ， 但 是 一 旦 Eureka 服 务 器 因为 某 种 原因 而 停机 ， 服 务 
注册 束 会 失败 。 为 了 避免 注册 失败 ， 最 好 是 为 服务 配置 两 个 或 更 多 的 
Eureka 实 例 : 


eureka: 
client: 


service-url: 
defaultZone: http://eurekal.tacocloud.com:8761/eureka/, 
http://eureka2.tacocloud.com:8762/eureka/ 





当 服 务 局 动 的 时 候 ， 它 会 答 试 使 用 zone 中 的 第 一 个 服务 砷 进行 注 
出。 如 末 因 为 条 种 原因 失败 ， 它 将 会 使 用 列表 中 的 下 一 个 服务 右 来 进行 
注册 。 最 终 ， 如 打出 现 故 障 的 服务 如 重新 恢复 在 线 状态 ， 它 将 会 从 对 等 
的 珊 上 复制 注册 信息 ， 这 样 就 能 将 该 服务 的 注册 条 目 包含 进来 。 


在 Eureka 中 注册 服务 只 完成 整个 任务 的 一 半 。 服 务 在 Eureka 注 册 之 
后 ， 其 他 的 服务 束 可 以 友 现 和 消费 它们 了 。 接 下 来 ， 我 们 看 一 下 如 何 消 
费 Eureka 中 注册 的 服务 。 


13.3.2 ”消费 服务 


在 消费 者 代码 中 ， 硬 编码 任何 服务 实例 的 URL 都 是 错误 的 做 法 。 这 
不 仪 会 让 消费 者 与 服务 的 特定 实例 粳 合 在 一 起 ， 而 且 一 旦 服务 的 主机 
和 /或 并 口 改变 ， 消 费 者 束 会 出 问题 。 


对 于 消费 者 应 用 来 说 ， 在 从 Eureka 中 查找 服务 时 ， 它 要 承担 很 多 责 
任 。Eureka 可 能 会 基于 得 找 结 末 返 回 同一 个 服务 的 多 个 实例 。 如 末 消 费 
者 请 求 ingredient-service 服 务 时 得 到 了 多 个 服务 实例 ， 那 么 它 该 如 何 选 
择 正 确 的 服务 呢 ? 


好 消息 是 消费 者 应 用 根本 不 需要 从 中 进行 选择 ， 甚 全都 不 需要 目 己 
显 式 地 进行 服务 查找 。 借 助 Spring Cloud 的 Eureka 客 户 端 文 持 和 Ribbon 客 
尸 红 负 载 均衡 磊 ， 我 们 可 以 很 容易 地 查找、 选择 和 消 恤 服务 实例 。 我 们 
有 两 种 方式 可 以 消 绩 从 Eureka 中 但 找到 的 服务 : 


。 文 持 负载 均衡 的 RestTemplate; 
。 Feign 生 成 的 客户 端 接口 。 
选择 哪 种 方式 在 很 大 程度 上 取决 于 个 人 豆 好 。 下 面 我 们 将 会 看 一 下 
这 两 种 方案 (首先 会 介绍 文 持 负载 均衡 的 RestTemplate〉， 然 后 你 束 可 
以 从 中 选择 最 喜欢 的 方式 了 。 


使 用 RestTemplate 消 费 服务 


你 对 Spring RestTemplate 各 户 奖 的 第 一 印象 可 能 来 产 于 第 7 章 。 我 们 
快速 回忆 一 下 它 的 运行 原理 ， 在 创建 或 注入 RestTemplate 之 后 ， 我 们 就 
可 以 友 运 HTTP 调 用 并 将 啊 应 绑 定 到 领域 类 型 上 。 例 如 ， 为 了 友 过 根 据 
ID 获取 配料 的 HITP GET 请 求 ， 我 们 可 以 使 用 如 下 的 RestTemplate 代 
伺 : 


public Ingredient getIngredientById(String ingredientId) { 
return rest.getForObject("http://localhost:8060806/ingredients/{id}", 


Ingredient.class, ingredientId); 





在 这 里 ， 唯 一 的 问题 在 于 getForObject0 的 URL 硬 编码 了 特定 的 主机 
和 端口 。 我 想 ， 你 可 能 会 将 细节 信息 提取 到 一 个 属性 中 ， 但 是 如 果 我 们 
将 请 求 的 目的 地 设置 成 配料 服务 众多 实例 中 的 菏 一 个 ， 那 么 我 们 所 配置 
的 URL 会 始终 都 指 癌 同一 个 特定 实例 ， 这 样 就 没有 人 负载 均衡 器 将 请 求 分 
敌 到 多 个 服务 实例 中 了 了 。 


如 果 我 们 将 应 用 变 成 Eureka 客 户 端 ， 束 可 以 声明 支持 负载 均衡 的 
RestTemplate bean 了 。 我 们 需要 做 的 承 是 声明 一 个 章 规 的 RestTemplate 


bean， 并 为 市 有 @Bean 注 解 的 方法 再 汪 、 加 上 人 @LoadBalanced: 


QBean 
Q@LoadBalanced 


public RestTemplate restTemplate() { 
return new RestTemplate(); 





} 


@OLoadBalanced 注 解 有 两 个 目的 。 首 先 ， 也 是 最 重要 的 ， 它 会 告诉 
Spring Cloud， 这 个 RestTemplate 要 能 够 通过 Ribbon 来 得 找 服务 。 其 次 ， 
它 会 作为 一 个 注入 限定 符 (gualifier) ， 所 以 有 两 个 或 更 多 RestTemplate 
bean 有 的话， 我 们 可 以 在 注入 的 地 方 声 明 此 处 想 要 文 持 负载 均衡 的 
RestTemplate。 


例如 ， 残 像 上 面 的 代码 那样 ， 我 们 想 要 使 用 文 持 负载 均衡 的 
RestTemplate 来 查找 配料 。 首 先 ， 我 们 将 文 持 负载 均衡 的 RestTemplate 注 
入 需要 它 的 bean 中 : 

QComponent 
public class IngredientServiceClient 1{ 
private RestTemplate rest; 


public IngredientServiceClient(@LoadBalanced RestTemplate rest) { 


this.rest = rest; 


} 





随后 ， 我 们 稍微 修改 一 下 getIngredientById0) 方 法 ， 使 用 服务 的 注册 
名 ， 而 不 再 明确 使 用 主机 和 问 口 : 


public Ingredient getIngredientById(String ingredientId) { 
return rest.getForObject( 


"http://ingredient-service/ingredients/{id}",， 
Ingredient.class, ingredientId); 





发 现 区 别 了 吗 ? getForObject0 的 URL 不 再 使 用 特定 的 主机 名 或 新 
口 。 在 主机 名 和 端口 的 位 置 上 ， 我 们 使 用 了 服务 名 ingredient-service。 
在 内 部 , RestTemplate 会 有 要求 Ribbon 根 据 名 称 奏 找 服 务 并 从 中 选择 一 个 实 
例 。Ribbon 非 常 乐于 效力 ， 它 会 将 URL 重 写 为 选 定 服务 实例 的 主机 和 端 
口 ， 然 后 让 RestTemplate 像 以 往 那 样 进行 处 理 。 


我 们 可 以 看 到 ， 使 用 文 持 负载 均衡 的 RestTemplate 与 标准 
RestTemplate 并 没有 太 关 的 差异 。 天 键 的 不 同 点 在 于 各 忆 媳 需要 使 用 服 
务 名 ， 而 不 是 显 式 的 主机 名 和 端口 。 如 末 你 想 使 用 WebClient 来 蔡 代 
RestTemplate 访 怎么 办 呢 ?WebClient 也 能 够 和 Ribbon 组 合 使 用 根据 名 称 
来 消费 服务 吗 ? 


使 用 WebClient 消 费 服务 


在 第 11 半 中， 我 们 看 到 WebClient 提 供 了 与 RestTemplate 类 似 的 
HTTP 客 户 端 ， 但 是 它 使 用 的 是 像 Flux 和 Mono 这 样 的 反应 式 类 型 。 如 果 
你 曾经 被 反应 去 编程 的 bug 所 困扰 ， 那 么 你 可 能 倾 癌 于 直接 使 用 
WebClient， 而 不 是 使 用 RestTemplate。 好 消息 是 ， 我 们 可 以 按照 与 
RestTemplate 美 似 的 方式 将 WebClient 作 为 文 持 负载 均衡 的 客户 内。 我 们 
需要 做 的 第 一 件 事 束 是 声明 一 个 返回 WebClient.Builder bean 的 方 读 ， 议 
方法 要 添加 @LoadBalanced 注 解 : 


QBean 

QLoadBalanced 

public WebClient.Builder webClientBuilder() { 
return WebClient.builder(); 


} 





在 声明 完 WebClient.Builder 之 后 ， 我 们 就 可 以 将 支持 负载 均衡 的 
WebClient.Builder 注 入 任何 需要 它 的 地 方 。 例 如 ， 我 们 可 以 将 它 注 入 
,半日 量 


IngredientServiceClient 的 构造 磊 中 : 


QComponent 
public class IngredientServiceClient 1{ 


private WebClient.Builder wcBuilder; 


public IngredientServiceClient( 
QLoadBalanced WebClient.Builder webclientBuilder wcBuilder) { 
this.wcBuilder = wcBuilder.,; 


} 





最 后 ， 在 我 们 需要 使 用 它 的 时 候 ， 可 以 利用 WebClient.Builder 构 建 
一 个 WebClient， 然 后 束 能 够 使 用 Eureka 注 册 的 服务 名 来 发 送 请 求 了 : 


public Mono<Ingredient> getIngredientById(String ingredientId) { 
return wcBuilder.build() 


‘get() 


.Uri("http://ingredient-service/ingredients/{id}", ingredientId) 
.retrieve().bodyToMono(Ingredient.class); 





与 文 持 人 负载 均衡 的 RestTemplate 类 似 ， 在 发 这 请 求 的 上 时候， 这 里 不 
需要 明确 指定 主机 和 端口 。 系 统 会 从 给 定 的 URL 中 抽取 出 服务 名 ， 通 过 
这 个 名 称 在 Eureka 中 查询 服务 。Ribbon 会 选择 服务 的 一 个 实例 ， 在 真正 


及 大 请 求 之 前 ， 会 根据 所 选 实例 的 主机 和 端口 重 与 URL。 


这 种 编程 模型 非常 容易 掌握 ， 夺 你 已 经 熟悉 RestTemplate 或 
WebClient 则 更 是 如 此 。Spring Cloud 还 有 一 个 技巧 ， 接 下 来 我 们 看 一 下 
如 何 使 用 Feign 创 建 基 于 接口 的 服务 客户 病 。 


定义 Feign 客 户 端 接口 

Feign 是 一 个 REST 和 客户 问 库 ， 使 用 一 种 特殊 的 、 接 口 驱 动 的 方式 来 
定义 REST 和 客户 疹 。 简 而 言 之 ， 如 采 你 喜欢 Spring Data 目 动 实现 
repository 接 口 的 方式 ， 那 么 你 肯定 会 喜欢 Feign 的 。 

Feign 最 初 是 Netflix 的 一 个 项 目 ， 后 来 变 成 了 独立 的 开源 项 目 ， 名 为 


OpenFeign。 单 词 feign 的 意思 是 “伪装 ”， 稍 后 我 们 将 会 看 到 对 于 假 疙 成 
REST 客 户 端 的 项 目 ， 这 是 一 个 很 合适 的 名 称 。 


要 使 用 Feign， 我 们 首先 需要 将 依赖 湛 加 到 项 目的 构建 文件 中 。 在 
pom.xml 文 件 中 ， 如 下 的 <dependency> 了 就 可 以 完成 该 任务 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-openfeign</artifactId> 
</dependency> 





在 使 用 Spring Initializr 的 时 候 ， 我 们 可 以 通过 选中 Feign 复 选 框 目 动 
添加 该 starter 依 赖 。 令 人 遗憾 的 是 ， 目 前 不 会 根据 已 有 的 依赖 启用 自动 
配置 功能 。 所 以 ， 我 们 需要 将 @EnableFeignClients 添 加 到 某 个 配置 类 
ul 


@Configuration 
@QEnableFeignClients 


public RestClientConfiguration { 
} 





现在 ， 到 了 有 意思 的 部 分 。 假 设 我 们 想 要 通过 注册 在 Eureka 中 名 为 
ingredient-service 的 服务 获取 一 个 Ingredient， 需 要 做 的 就 是 定义 如 下 的 
接口 : 


package tacos.ingredientclient.feign; 

Import org.springframework.cloud.openfeign.FeignClient; 
import org.springframework.web.bind.annotation.GetMapping; 
import org.springframework.web.bind.annotation.PathVariable; 
Import tacos.ingredientclient.Ingredient; 


QFeignClient("ingredient-service") 

public interface IngredientClient { 
@QGetMapping("/ingredients/{id}") 
Ingredient getIngredient(@PathVariable("id") String id); 





} 


这 是 一 个 很 简单 的 接口 ， 并 没有 实现 类 。 在 运行 期 ， 当 Feign 及 现 
它 的 时 候 ， 这 一 切 就 都 不 重要 了 ，Feign 会 目 动 创 建 一 个 实现 类 并 将 其 
对 露 为 Spring 应 用 上 下 文中 的 bean。 


仔细 观察 一 下 ， 我 们 会 发 现 其 中 有 一 些 注解 在 及 挥 作用 ， 并 将 所 有 
功能 组 合 在 了 一 起 。 接 口上 的 @FeignClient 注 解 会 指定 该 接口 上 的 所 有 
方法 都 会 对 名 为 ipgredient-service 的 服务 发 送 请 求 。 在 内 部 ， 服 务 将 会 
通过 Ribbon 进 行 得 找 ， 这 与 文 持 负载 均衡 的 RestTemplate 运 行 方式 是 一 
样 的 。 


随后 束 是 getIngredient() 方 法 ， 它 使 用 了 @GetMapping 注 解 。 你 会 发 
现 ， 这 个 注解 来 源 于 Spring MVC。 确 实 ， 就 是 同一 个 注解 。 现 在 它 用 在 


了 客户 问 ， 而 不 是 用 在 控制 磊 上 。 它 表明 ， 任 何 对 getIngredient() 的 调用 
都 会 对 “/ingredients/{id}” 路 径 发 起 GET 请 求 ， 其 中 的 主机 和 端口 是 通过 
Ribbon 选 定 的 。@PathVariable 注 解 同样 来 和 目 Spring MVC， 会 将 方法 参 
数 映 喘 到 给 定 路 人 径 的 占 位 从 上 。 


现在 ， 我 们 需要 做 的 就 是 将 Feign 实 现 的 接口 注入 需要 的 地 方 并 开 
始 使 用 它 。 例 如 ， 要 在 控制 融 中 使 用 它 ， 我 们 可 以 这 样 做 : 


@Controller 
@QRequestMapping("/ingredients") 
public class IngredientController { 


private IngredientClient client; 


QAutowired 
public IngredientController(IngredientClient client) { 
this.client = client; 


} 


@QGetMapping("/{id}") 
public String ingredientDetailPpage(@PathVariable("id") String id, 
Model model) { 
model.addAttribute("ingredient", client.getIingredient(id)); 
return "ingredientDetail"; 


} 





} 


我 不 知道 你 的 观点 如 何 ， 但 是 我 觉得 这 非 沼 流畅! 很 难说 我 最 辟 欢 
哪 种 方式 : 支持 负载 均衡 的 RestTemplate、WebClient， 还 是 具有 魔力 的 
Feign 各 户 姗 接口 。 不 管 选 择 哪 种 方式 ， 我 们 的 REST 各 刀 闪 都 能 根据 名 
称 消 费 在 Eureka 注 册 的 服务 ， 避 免 硬 编码 特定 的 主机 名 和 端口 。 


值得 一 提 的 是 ，Feign 提 供 了 自己 的 注 骨 。@RequestLine 和 @Param 
非常 类 似 于 Spring MVC 中 的 @RequestMapping 和 (@PathVariable， 但 是 它 


们 的 使 用 方式 略 有 兰 开 。 能 够 在 客户 站 便 用 我 们 已 经 非 营 熟 芒 的 Spring 
MVC 注 解 是 非常 标的， 而 且 它 们 很 可 能 与 我 们 在 定义 服务 控制 套 时 所 
使 用 的 注解 是 一 样 的 。 


13.4 ”小结 


。 信 助 目 动 配置 和 @EnableEurekaServer 注解 ，Spring Cloud Netflix 能 
够 让 我 们 很 容易 地 创建 Netflix Eureka 服 务 注 册 中 心 。 

例 服 务 可 以 使 用 名 字 将 它们 目 身 注册 到 Eureka 中 ， 这 样 可 以 航 其 他 
服务 友 现 。 

在 客户 端 ， 作 为 客户 疹 负 载 均衡 器 ，Ribbon 能 够 根据 名 称 碍 找 服务 
并 选择 实例 。 

客户 端 代码 可 以 使 用 RestTemplate， 利 用 Ribbon 进 行 负载 均衡 ;也 
可 以 将 REST 客 户 端 定义 为 接口 ， 由 Feign 在 运行 期 自动 实现 。 
不 管 采 用 哪 种 方案 ， 各 刀 冰 代码 都 不 需要 使 编 但 它们 所 消费 的 服务 
的 地 址 。 





[有 征 的 ， 在 这 部 电影 中 ， 真 正 的 问题 是 喂 Mogwai 的 时 间 ， 也 残 是 午 
夜 时 分 。 没 有 一 个 闫 比 是 完 关 的 。 


[2] 在 这 里 ， 我 们 会 关注 如 何 使 用 Java 和 Spring 编写 微服 务 。 如 果 你 对 
如 何 使 用 .NET 编 写 微 服务 并 与 Spring Cloud 服 务 交 互感 兴趣 ， 那 么 可 以 
参考 一 下 Steeltoe。 


。 运行 Spring Cloud Config Server 


。 创建 Config Server 的 客户 端 


。 三 储 敏感 配置 


。 目 动 化 刷新 配置 





买 过 房子 或 汽车 的 人 可 能 都 会 面临 厘 厚 的 一 登 纸 。 购 买 大 宗 商 品 时 
要 签 普 的 合同 往往 会 对 无 纸 化 社会 的 承 庆 不 导 一 顾 。 每 当 我 与 汽车 经 销 
商 或 代理 人 坐 到 一 起 的 时 候 ， 都 感 贫 我 应 该 手 前 准备 好 一 登 崩 市 ， 为 这 
个 过 程 中 几乎 总 能 出 现 的 纸 划 伤 手 的 情况 做 好 准备 。 


近年 来 ， 尽 管 我 必须 要 签 普 的 总 页 数 儿 乎 没有 什么 变化 ， 但 是 我 不 
必 像 以 前 那样 填写 那么 多 的 字段 了 。 对 于 表格 中 那些 曾经 手动 填写 的 地 
方 ， 现 代 化 的 表格 在 打印 之 前 通 稼 惑 基 于 收集 到 的 数据 预 匈 填充 好 了 。 
这 样 的 话 ， 不 但 会 加 快 处 理 速 度 ， 而 且 能 够 减少 在 多 个 表格 间 手 动 填写 


重复 数据 所 导致 的 铬 误 。 


与 乙 闫 似 ， 很 多 应 用 程序 都 存在 东 种 形式 的 配置 。 在 第 5 草 中 ， 我 
们 讨论 了 通过 配置 属性 来 设置 Spring Boot 应 用 。 通 常 ， 我 们 设置 的 属性 
是 该 应 用 特有 的 ， 所 以 可 以 通过 application.properties 或 application.yml 文 
件 声 明 这 些 属 性 ， 并 将 它们 打包 人 到 应 用 的 部 闭 文 件 中 。 


按照 微服 务 的 方式 来 组 织 染 构 的 话 ， 多 个 服务 之 则 的 配置 属性 是 退 
用 的 。 残 像 手 工 需 写 市 有 重复 数据 的 表单 非 钊 乏味 而 且 匈 于 出 钳 一 样 ， 
路 多 个 应 用 服务 重复 进行 配置 可 能 也 会 存在 问题 。 


在 本 章 中 ， 我 们 将 会 研究 Spring Cloud 的 Config Server， 这 是 为 指定 
应 用 中 所 有 服务 提供 集中 式 配 置 的 一 个 服务 。 借 助 配置 服务 器 ， 我 们 可 
以 在 一 个 地 方 官 理 所 有 的 应 用 配置 ， 避 人 免 任何 重 复 。 


但 是 在 开始 之 前 ， 我 们 简 里 思考 一 下 单独 配置 做 服务 的 问题 ， 以 及 
中 心 化 的 配置 为 何 能 够 更 好 。 


14.1 共计 配置 


束 像 我 们 在 第 5 章 所 看 到 的 那样 ， 我 们 可 以 通过 多 种 属性 源 设 置 属 
性 来 对 Spring 应 用 进行 配置 。 如 末 霖 个 配置 属性 可 能 会 更 改 或 者 只 针对 
运行 时 环境 有 效 ， 那 么 Java 系 统 属 性 或 操作 系统 环境 变量 是 一 个 合适 的 
可 选 方案 。 对 于 不 太 可 能 发 生变 化 或 者 应 用 特定 的 属性 ， 将 它们 放 到 
application.yml 或 application.properties 中 ， 随 看 打包 的 应 用 一 起 部 闭 是 一 
种 很 好 的 方案 。 


这 些 方案 对 于 简单 的 应 用 来 说 都 很 不 销 。 但 是 ， 当 在 环境 变量 或 
Java 系 统 属性 中 设置 配置 属性 的 时 候 ， 我 们 必须 要 接受 这 样 一 个 现实 ， 
那 就 是 修改 这 些 属性 需要 应 用 重启 。 如 果 我 们 选择 将 属性 打包 到 要 部 署 
的 JAR 或 WAR 文 件 中 ， 那 么 在 属性 变更 时 ， 我 们 必须 要 完全 重新 构建 和 
重新 部 闭 应 用 。 如 末 我 们 想 要 回 滚 配置 变更 ， 那 么 同样 的 约束 依然 有 
XC 


这 些 约束 在 有 些 应 用 程序 中 是 可 以 接受 的 。 但 是 ， 在 有 些 情况 下 ， 
如 末 仅 仅 是 为 了 修改 一 个 属性 融 重 司 应 用 ， 往 好 了 说 是 不 太 方 便 ， 往 坏 
了 说 则 有 共有 破坏 性 。 除 此 之 外 ， 在 基于 微服 务 架 构 的 应 用 中 ， 属 性 管理 
会 跨越 多 个 代码 库 和 部 闭 实 例 ， 因 此 将 相同 变更 用 到 应 用 中 多 个 服务 的 
每 个 实例 中 是 不 现实 的 。 


有 些 属 性 十 敏感 的 ， 比 如 数据 库 密码 和 其 他 类 型 的 私密 信息 。 尺 官 
这 些 值 作为 应 用 的 属性 在 写 入 的 时 候 可 以 进行 加 密 ， 但 是 应 用 在 使 用 它 
们 之 前 必须 要 乞 解密。 即便 如 此 ， 有 些 属 性 其 全 可 能 需要 对 应 用 开 及 人 
员 保密 。 这 样 的 话 ， 将 它们 设置 成 环境 变量 或 者 将 它们 与 应 用 的 其 他 代 
但 一 起 通过 源码 控制 系统 进行 管理 惑 是 不 可 取 的 了 。 


相反 ， 我 们 可 以 考 压 一 下 这 些 场 景 在 集中 二 的 配置 过 理 下 会 是 什么 
样子 。 


配置 不 再 需要 和 应 用 程序 代码 一 起 打包 和 部 普 。 这 伞 的 话 ， 配 站 的 
变更 或 回 滚 了 融和 都 不 需要 重新 构建 和 重新 部 普 应 用 了 。 配 置 甚 至 可 以 
在 运行 时 进行 变更 ， 无 须 重 新 司 动 应 用 。 

共享 通用 配置 的 微服 务 不 需要 管理 自己 的 属性 设置 副本 ， 并 且 能 够 


管理 共 吝 的 相同 属性 。 如 采 需 要 对 属性 进行 变更 ， 那 么 这 些 变更 只 
逢 在 一 个 地 方 执 行 一 次 就 可 以 应 用 a 到 所 有 的 微服 务 上 。 

敏感 配置 可 以 进行 加 密 ， 并 且 能 够 与 应 用 代码 分 开 进行 维护 。 应 用 
可 以 按 需 获取 未 加 密 的 值 ， 而 不 需要 应 用 程序 提供 解密 信息 相关 的 
代码 。 


Spring Cloud Config Server 提 供 了 中 心 化 的 配置 功能 ， 应 用 中 的 所 
有 做 服务 均 可 以 依赖 该 服务 颖 来 获取 配置 。 因 为 它 是 中 心 化 的 ， 所 以 是 
一 个 一 站 式 的 配置 商店 ， 所 有 的 服务 都 可 以 使 用 它 ， 为 外 它 还 能 够 为 特 
定 服务 提供 专门 的 配置 。 


使 用 Config Server 的 第 一 步 束 是 创建 并 运行 该 服 务 右 。 
14.2 ”运行 配置 服务 天 


Spring Cloud Config Server 为 配置 数据 提供 了 中 心 化 的 数据 源 。 与 
Eureka 类 似 ， 我 们 可 以 将 Config Server 视 为 另 一 个 微服 务 ， 在 更 大 的 应 
用 中 ， 它 的 角色 就 是 为 应 用 中 的 其 他 服务 提供 配置 数据 。 


Config Server 暴 露 了 REST API， 客 户 端 〈 也 束 是 其 他 的 服务 ) 可 以 
通过 它 来 消费 配置 属性 。 通 过 Config Server 提 供 的 配置 来 源 于 Config 
Server 之 外 ， 通 销 来 源 于 一 个 像 Git 这 样 的 源码 控制 系统 。 图 14.1 曾 述 了 
它 是 如 何 运 行 的 。 





Oat 


and/or 





配置 属性 





Spring Cloud 
Config Server 





图 14.1 Spring Cloud Config Server 通 过 支撑 的 Git 仓 库 或 Vault 私 密 存 储 来 为 其 他 服务 提供 配置 属 
性 


注意 ， 在 图 14.1 中 ， 我 使 用 的 是 Git 的 图 标 ， 而 不 是 GitHub 的 图 标 。 
这 是 很 午 要 的 ， 我 们 可 以 使 用 任意 的 Git 实 现 来 存储 配置 信息 ， 包 括 但 
不 限于 GitHub。GitLab、 和 微软 的 Team Foundation Server 和 Gogs 都 是 合法 
的 Config Server 后 疹 可 选 方案 。 


注意 : 不 管 使 用 哪个 Git 服 务 右 ，Config Server 儿 平 没 有 什么 
差异 。 在 这 里 ， 我 选择 使 用 Gogs， 这 是 一 个 轻 量 级 、 易 于 搭建 


的 Git 服 务 右 。 更 具体 来 计 ， 我 在 开 友 使 用 的 机 需 运 行 Gogs 时 完 
全 半 循 了 Docker 中 运行 Gogs 的 指南 。 





将 配置 信息 存 人 备 在 像 Git 这 样 的 源 但 控制 系统 中 ， 配 置 可 以 像 应 用 
源码 那样 实现 厂 本 化 、 使 用 分 文 、 添 加 标签 、 恢 复 和 指摘 〈blame) 。 


但 是 ， 为 了 让 配置 信息 与 使 用 它们 的 源码 分 离 ， 这 些 配 置 可 以 独立 于 应 
用 演化 和 版 本 化 。 


你 可 能 注意 到 了 ， 在 图 14.1 中 还 包含 了 HashiCorp Vault。 如 果 想 要 
你 持 配 置 属性 完全 私密 ， 并 且 要 将 它们 锁 起 来 直到 逢 要 的 时 候 才 取出 ， 
那么 Vault 非 常 有 用 。 我 们 将 会 在 14.5 节 中 讨论 如 何 组 合 使 用 Config 
Server 和 和 Vault。 


14.2.1 局 用 配置 服务 妖 


作为 更 大 应 用 系统 中 的 一 个 微服 务 ，Config Server 会 作为 一 个 独立 
的 应 用 进行 开 肥 和 部 奢 。 所 以 ， 我 们 需要 为 Config Server 创 建 一 个 全 新 
的 项 目 。 要 实现 这 一 点 ， 最 人 简 蛙 的 方式 束 古 使 用 Spring Initializr 或 它 的 
某 个 客户 并 (比如 Spring Tool Suite 中 的 New Spring Starter Project 辐 


叶 ) 。 


配 首 : 重 载 的 术语 


当 我 们 讨论 Spring Cloud Config Server 的 时 候 ， 会 经 常用 
到 “配置 (configuration) ”这 个 术语 ， 但 是 它 所 指 的 并 不 总 是 同 


一 件 事 。 我 们 将 会 编写 配置 属性 来 配置 Config Server 本 里 。 同 
时 ，Config Server 还 会 为 应 用 提供 配置 属性 。Config Server 的 名 
字 中 还 有 “Config” 这 个 单词 ， 这 会 导致 一 定 的 混乱 。 





在 使 用 “configuration” 这 个 单词 的 时 候 ， 我 都 会 尽力 表达 清 
楚 到 的 指 的 是 哪个 配置 ， 而 在 代 指 Config Server 的 时 候 ， 我 都 会 
使 用 “Config” 这 个 缩写 形式 。 





我 一 般 会 将 项 目 命名 为 “config-server”， 但 是 你 可 以 选取 任何 你 喜 
欢 的 名 称 。 最 重要 的 是 要 选中 Config Server 复 选 框 ， 这 样 束 能 声明 对 
Config Server 的 依 顿 。 这 样 做 的 结果 吏 是 会 在 所 生成 项 目的 pom.xml 文 
件 中 添加 如 下 的 依赖 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-config-server</artifactId> 
</dependency> 





Config Server 的 版 本 是 根据 选择 的 Spring Cloud release train 确 定 的 。 
在 pom.xml 文 件 中 ， 必 须要 配置 Spring Cloud release train。 在 我 编写 本 书 
的 时 候 ， 了 最 新 的 Spring Cloud 发 布 版 本 是 Finchley.SR1。 所 以 ,在 
pom.xml 文 件 中 将 会 发 现 如 下 的 属性 和 <dependencyManagement> 代 人 码 
块 : 





<properties> 


<spring-cloud.version>Finchley.SR1</spring-cloud.version> 
</properties> 


<dependencyManagement> 
<dependencies> 
<dependency> 
<grouplId>org.springframework.cloud</groupId> 
<artifactId>spring-cloud-dependencies</artifactId> 


<version>${spring-cloud.version}</version> 
<type>pom</type> 
<scope>import</scope> 
</dependency> 
</dependencies> 
</dependencyManagement> 





尽管 Config Server 依 赖 将 Spring Cloud 添 加 到 了 项 目的 类 路 径 下 ， 但 
是 这 里 并 没有 日 动 配置 局 动 它 ， 所 以 我 们 需要 为 和 攻 个 配置 类 添加 
@EnableConfigServer。 顾 名 思 义 ， 这 个 注解 会 在 应 用 运行 的 时 候 局 用 一 
个 Config Server。 通 常 ， 我 会 将 @EnableConfigServer 放 到 主 类 中 ， 如 下 
所 示 : 


@EnableConfigServer 
@SpringBootApplication 
public class ConfigServerApplication { 
public static void main(String[|] args) { 
SpringApplication.run(ConfigServerApplication.class, args); 





在 我 们 想 要 启动 应 用 并 查看 Config Server 如 何 运 行 之 前 ， 必 须 还 要 
做 另外 一 件 事情 : 我 们 必须 要 告诉 它 ， 它 要 对 外 提供 的 配置 属性 都 位 于 
何 处 。 作 为 开始 ， 我 们 将 会 使 用 来 目 Git 仓 库 的 配置 ， 所 以 我 们 需要 将 
spring.cloud.config.server.git.uri 必 性 设置 为 配置 仓库 的 URL: 
spring: 


cloud: 
config: 


server : 
2it: 
uri: https://github.com/tacocloud/tacocloud-config 





在 14.2.2 小 节 ， 我 们 将 会 看 到 如 何 为 Git 仓 库 填充 属性 。 


为 了 在 本 地 开 友 坏 境 运 行 ， 我 们 可 能 还 要 配置 男 一 个 属性 。 在 测试 
本 地 服务 的 时 低 ， 我 们 最 终 会 有 多 个 服务 一 直 运 行 并 且 它 们 要 监 昕 
localhost 的 不 同 端口 。 作 为 典型 的 Spring Boot Web 应 用 ，Config Server 
堆 认 会 监听 8080 疹 口 。 为 了 避免 交口 冲突 ， 我 们 可 以 通过 设置 
server.port 属 性 指定 一 个 唯一 的 端口 号 : 


SerVver. 

在 这 里 ， 我 们 将 server.port 设 置 为 8888， 是 因为 在 14.3 节 中 我 们 将 会 
看 到 这 是 Config 客 户 闪 试图 获取 配置 信息 时 默认 使 用 的 亲口。 可 以 将 其 
设置 成 任意 但 ， 但 是 在 配置 客户 端 服 务 中 必须 要 与 其 匹配 。 


很 重要 的 一 点 需要 注意 ， 我 们 此 时 所 编 与 的 配置 是 针对 Config 
Server 本 里 的 。 它 与 Config Server 对 外 提供 的 配置 是 不 同上 时。Config 
Server 会 对 外 提供 从 Git 或 Vault 获 取 到 的 配置 信息 。 


此 时 ， 如 采 局 动 应 用 ， 允 会 有 一 个 监听 8888 奖 口 的 Config Server， 
它 还 不 能 提供 任何 的 配置 属性 。 我 们 目前 还 没有 任何 Config Server 客 户 
疾 ， 但 是 可 以 通过 curl 命 令 行 ( 或 者 提供 同样 功能 的 HTTP 客 尸 闹 ) 模拟 
一 个 客户 痛 : 





$ curl localhost:8888/application/default 
{ 
"name": "application", 
"profiles": | 
"default" 
] ， 
"label": null, 
“Verslon : "ca791b15df6@7ce41d36c24937eece4ec4b2868f4d"， 
“State : null, 


"propertySources": | 


它 会 癌 Config Server 的 “application/default” 路 径 发 送 HTTP GET 请 
求 。 这 个 请 求 可 以 由 两 部 分 或 3 部 分 组 成 ， 如 图 14.2 所 示 。 
Config server 的 主机 和 端口 处 于 激活 状态 的 Spring profile 


http://localhost:8888/application/default/master 


应 用 的 名 称 Git 标 签 /分 文 〈 可 选 ) 


(spring.application.name) 


图 14.2 ”Config Server 对 外 暴露 了 一 个 REST API (通过 它 可 以 消费 配置 属性 )》 


路 径 的 第 一 部 分 ， 即 “application”， 指 的 是 发 送 请 求 的 应 用 的 名 
称 。 在 14.4.1 小 和 中 将 会 看 到 ，Config Server 是 如 何 利用 请 求 路 径 中 这 部 
分 的 内 容 为 我 们 提供 特定 应 用 配置 的 。 现 在 ， 我 们 没有 特定 应 用 的 配 
置 ， 所 以 任意 全 都 是 可 以 的 。 


路 径 的 第 二 部 分 指 的 是 及 送 请 求 的 应 用 中 处 于 激 话 状态 的 Spring 
profile。 在 14.4.2 小 节 中 ， 我 们 将 会 看 到 Config Server 是 如 何 利 用 请 求 路 
径 中 有 的 profile 值 提供 油 活 active 特 定 配 置 和 的。 我 们 目前 没有 特定 profile 的 
配置 ， 所 以 任意 的 profile 值 都 是 可 以 的 。 


路 径 的 第 三 部 分 是 可 选 的 ， 指 定 了 提供 配置 信息 的 后 总 Git 仓 库 的 
未 签 或 分 支 。 如 果 没 有 指定 ， 那 么 默认 会 使 用 “master” 分 文 。 


请 求 的 啊 应 为 我 们 提供 了 一 些 天 于 Config Server 的 基本 信息 ， 包 括 
为 我 们 提供 配置 信息 的 Git 提 交 的 版 本 和 标 位 。 但 是 ， 这 里 明显 缺少 的 


束 是 真正 的 实际 配置 信息 。 正 和 党 情况 下 ， 我 们 会 在 propertySources 属 性 
下 看 到 它们 ， 但 是 在 这 个 啊 应 中 ， 它 是 空 的 。 这 是 因为 我 们 需要 为 Git 
仓库 填充 Config Server 要 对 外 提供 的 属性 。 现 在 ， 我 们 看 一 下 该 如 何 实 
现 。 


14.2.2 ”填充 配置 仓库 


我 们 有 多 种 办 法 为 Config Server 提 供 属性 ， 最 基本 、 最 直接 的 方 采 
是 提交 application.properties 或 application.yml 文 件 到 Git 仓 库 的 根 路 径 
下 
假设 我 们 已 经 推送 了 一 个 名 为 application.yml 的 文件 到 前 面 章 币 所 
配置 的 Git 仓 库 下 。 这 个 配置 文件 与 前 面 章节 的 配置 是 不 同 的 ， 它 是 
Config Server 将 要 对 外 提供 的 配置 。 假 设 在 这 个 application.yml 文 件 中 我 
们 配置 了 如 下 的 属性 : 


server : 
port: 6 


eureka: 
client: 
service-url: 
defaultZone: http://eurekal:8761/eureka/ 





立 管 这 个 application.yml 文 件 的 内 容 并 不 多， 但 是 它 所 定义 的 配置 
是 相当 和 章 要 的 。 它 会 守 诉 应 用 中 的 每 个 服务 部 选择 任意 可 用 的 剖 口 并 且 
告诉 它们 进行 服务 注册 的 Eureka 在 哪里 。 这 意味 看 ， 在 14.3 节 中 ， 当 我 
们 将 服务 变 成 Config Server 各 户 站 的 时 候 ， 我 们 可 以 从 服务 中 移 除 叱 陈 


的 Eureka 配 置 。 


作为 Config Server 的 客户 闫 ， 我 们 可 以 使 用 cu 命令 行 租 看 Config 
Server 捉 供 的 新 配置 数据 : 


$ curl localhost:8888/someapp/someconfig 
{ 
"name": “Someapp ， 
"profiles": | 
"someconfig" 


"version": "95dfe@cbc3bca166199bd8864b27alde7yc3ef5c35e"， 
"state": null, 
"propertySources": |[ 


"name": "http://localhost:1608060/habuma/tacocloudconfig/ 
application.yml",， 
"source": 1{ 
"server.port": 0， 
"eureka.client.service-url.defaultZone": 
"http://eurekal:8761/eureka/" 





与 之 前 对 Config Server 的 请 求 不 同 ， 这 个 啊 应 的 propertySources 属 性 
中 有 J 了 内 容 。 其 体 来 计 ， 它 包含 了 一 个 属性 源 ， 属 性 源 的 name 属 性 指 问 
了 Git 仓 库 的 引用 ，source 则 包含 了 我 们 推送 至 Git 仓 库 中 的 属性 。 


从 Git 于 路 径 下 所 供 配 置 


按照 代码 的 组 织 风 格 ， 你 可 能 想 要 将 配置 信息 存储 到 Git 仓 库 的 子 
目录 下 ， 而 不 是 放 到 根 路 径 下 。 例 如 ， 我 们 想 要 将 配置 放 到 相对 于 Git 
仓库 根 目 录 名 为 “config” 的 子 目 录 下 ， 束 可 以 按照 如 下 方式 设置 


spring.cloud.config.server.git.search-paths 属 性 ， 让 Config Server 个 再 从 根 
目录 而 是 从 “/config” 上 日 录 下 提供 配置 信息 : 


spring: 
cloud: 
config: 


server: 
2it: 
uri: http://localhost:160806/tacocloud/tacocloud-config 
search-paths: config 





注意 ，spring.cloud.config.server.git.search-paths 属 性 是 一 个 复数 形 
式 ， 这 意味 大 我 们 可 以 让 Config Server 提 供 来 日 多 个 路 竹 的 配置 ， 只 需 
将 它们 列 出 来 以 逗号 分 隅 即 可 : 


Eile 


spring: 
cloud: 
config: 
server : 
2it: 
uri: http://localhost:160806/tacocloud/tacocloud-config 
search-paths: config,moreConfig 





这 样 的 话 ，Config Server 会 提供 Git 仓 库 下 来 
自 “%config” 和 “moreConfig” 路 径 的 配置 。 


我 们 还 可 以 使 用 通配符 指定 搜索 路 径 : 


Spring : 
cloud: 
config: 


server : 
2it: 
uri: http://localhost:16086/tacocloud/tacocloud-config 
search-paths: config,more* 





这 里 ，Config Server 会 提供 来 自 “%config” 和 所 有 以 “more” 开 头 的 子 
目录 的 配置 。 


从 Git 分 文 或 祭 丛 下 近 供 配置 


默认 情况 下 ，Config Server 会 提供 Git 中 master 分 支 下 的 配置 。 在 客 
尸 颖 ， 我 们 可 以 将 特定 分 支 或 标签 设置 为 请 求 Config Server 路 径 的 第 三 
个 成 员 ， 如 图 14.2 所 示 。 但 是 ， 我 们 可 能 会 发 现 让 Config Server 上 默认 请 
求 Git 下 特定 的 标签 或 分 文 会 非常 有 用 ， 而 不 是 默认 使 用 master。 
spring.cloud.config.server.git.default-label 属 性 可 以 重 写 默认 的 标签 或 分 
bp 


例如 ， 考 虑 如 下 的 配置 ， 它 会 让 Config Server 提 供 名 为 “sidework” 的 
分 文 (或 标签 ) 下 的 配置 : 


spring: 
cloud: 
config: 


server : 
2it: 
uri: http://localhost:160806/tacocloud/tacocloud-config 
default-label: sidework 





按照 这 个 配置 形式 ， 除 非 Config Server 客 户 端 指定 ， 和 否则 将 会 提 
供 “sidework” 分 文 下 的 配置 。 


为 Git 后 是 近 供 认证 


Config Server 检 索 配 置信 息 的 后 问 Git 仔 库 很 可 能 会 使 用 用 户 名 和 密 


人 码 进 行 保护。 如 果 是 这 样 ， 我 们 就 必须 为 Config Server 提 供 Git 仓 库 的 插 
证 信息 。 


spring.cloud.config.server.username 和 和 
Spring.cloud.config.server.password 属 性 可 以 为 后 端 仓 库 设 置 用 户 名 和 密 
人 码 。 如 下 的 Config Server 配 置 将 设置 这 些 属性 : 


Spring : 
cloud: 
config: 
server: 


2it: 
uri: http://localhost:160806/tacocloud/tacocloud-config 
Username: tacocloud 
password: s3cr3tP455werd 





在 这 里 ， 分 别 将 用 尸 名 和 和 密码 设置 成 了 tacocloud 和 和 
S3cr3tP455w0Ord 。 


使 用 curl 作 为 Config Server 的 客户 并 能 够 帮助 我 们 体验 一 下 Config 
Server 是 怎样 运行 的 。 实 际 上 ，Config Server 所 能 做 的 远 远 不 止 于 此 。 
但 是 ， 我 们 所 编写 的 微服 务 并 不 会 使 用 curl 来 获取 配置 数据 。 所 以 在 碍 
看 Config Server 提 供 配置 的 其 他 方式 之 前 ， 我 们 将 关注 点 转移 到 微服 务 
上 ， 看 一 下 如 何 将 它们 变 成 Config Server 的 客户 痊 。 


14.3 ”消费 共享 配置 


除了 提供 中 心 化 的 配置 服务 器 ，Spring Cloud Config Server 还 提供 
了 一 个 客户 端 库 ， 它 会 包含 在 Spring Boot 应 用 的 构建 文件 中 ， 人 允许 应 用 


成 为 Config Server 的 客户 着 。 


将 Spring Boot 应 用 变 成 Config Server 客 户 端 的 最 简单 方式 就 是 添加 
如 下 的 依赖 到 项 目的 Maven 构 建文 件 中 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-config</artifactId> 
</dependency> 





相同 的 依赖 也 可 以 在 Spring Initializr 中 通过 选择 标签 为 Config Client 
的 复 选 框 添加 进来 。 


当 应 用 局 动 的 时 候 ， 目 动 配置 功能 将 会 自动 化 地 注册 一 个 属性 源 ， 
该 属性 源 将 会 从 Config Server 中 拉 取 属性 。 默 认 情 况 下 ， 它 会 假定 
Config Server 运 行 在 localhost 并 监听 8888 端 口 。 如 果 情 况 并 非 如 此 ， 我 
们 可 以 通过 设置 Spring.cloud.config.uri 配 置 Config Server 的 位 置 : 


Spring : 
cloud: 


config: 
uri: http://config.tacocloud.com:8888 





需要 清楚 一 扣 ， 这 些 属性 必须 要 帮 人 到 Config Server 竹 户 蜗 应 用 的 本 
地 ， 比 如 随 每 个 微服 务 打 包 和 部 闭 的 application.yml 或 
application.properties 文 件 中 。 


现在 ， 我 们 有 了 一 个 中 心 化 的 配置 服务 磺 ， 几 乎 所 有 的 配置 都 将 会 
由 它 来 提供 ， 每 个 微服 务 都 不 需要 携带 很 多 目 己 的 配置 了 。 正 第 情况 
下 ， 我 们 只 需要 设置 Spring.cloud.config.uri 属 性 来 指定 配置 服务 器 的 地 址 


并 设置 Spring.application.name 属 性 为 配置 服务 喜 指 明 当 前 应 用 即 可 。 


哪个 优先 : Config Server 还 是 服务 注册 中 心 ? 


我 们 正在 设置 微服 务 ， 让 它们 通过 Config Server 了 解 Eureka 
服务 注册 中 心 在 什么 地 方 。 这 是 一 种 通用 的 方式 ， 能 够 避免 在 应 
用 的 每 个 微服 务 中 重复 服务 注册 中 心 的 细节 信息 。 


同时 ， 我 们 还 可 能 会 将 Config Server 本 身 注 册 到 Eureka 中 ， 
并 让 每 个 微服 务 像 发 现 其 他 服务 那样 去 查找 Config Server。 如 果 


你 喜欢 这 种 模式 ， 束 需要 将 Config Server 变 成 服务 发 现 的 客户 
闹 ， 并 将 spring.cloud.config.discovery.enabled 属 性 设置 为 false。 
这 样 的 话 ，Config Server 会 将 日 里 以 “configserver” 名 称 注 册 到 
Eureka 中 。 


这 种 方式 的 缺点 在 于 ， 每 个 服务 在 局 动 的 时 候 都 要 调用 两 次 
外 部 的 服务 : 第 一 次 调用 Eureka 有 发现 Config Server 的 位 置 ， 第 二 
次 调用 Config Server 获 取 配 置 数 据 。 





当 应 用 启动 的 时 候 ，Config Server 客 户 端 提供 的 属性 源 将 会 对 
Config Server 友 送 请 求 。 它 所 接收 到 的 属性 将 会 放 到 应 用 的 环境 之 中 。 
除 此 之 外 ， 这 些 属 性 实际 上 还 会 被 缓存 起 来 ， 即 便 Config Server 售 机， 
它们 依然 是 可 用 的 (我 们 将 会 在 14.6 节 看 一 下 在 属性 发 生变 更 的 时 候 ， 
刷新 它们 的 几 种 方式 ) 。 


到 目前 为 止 ，Config Server 提 供 的 配置 都 非 钊 简单 ， 面 回 所 有 的 应 
用 和 上 所 有 的 profile。 但 有 时 候 ， 我 们 需要 提供 符 定 应 用 专 有 的 配置 ， 或 
者 握 供 当 应 用 在 特定 profile 处 于 激活 状态 时 才 可 用 的 配置 。 我 们 看 一 下 
Config Server 的 另 一 面 ， 看 看 使 用 它 的 几 种 方式 ， 包 括 提 供 特 定 应 用 和 
特定 profile 的 属性 。 


14.4 近 供 特定 应 用 和 profile 的 属性 


我 们 可 以 回忆 一 下 ， 当 Config Server 客 户 端 启动 的 时 候 ， 它 会 发 送 
一 个 请 求 到 Config Server 中 ， 这 个 请 求 的 路 人 径 中 会 包含 应 用 的 名 称 和 激 
活 profile 的 名 称 。 在 提供 配置 数据 的 时 候 ，Config Server 会 考虑 这 些 
什 ， 并 为 澡 亡 疹 返 回 特定 应 用 和 特定 profile 的 配置 数据 。 


从 客 尸 问 的 角度 来 讲 ， 消 费 特 定 应 用 和 特定 profile 的 配置 属性 与 之 
前 没有 Config Server 时 并 没有 太 大 的 舌 别 。 应 用 的 名 称 可 以 通过 
spring.application.name 属 性 (这 与 Eureka 识 别 应 用 的 属性 名 是 相同 的 》 
来 指定 应 用 的 名 称 。 激 活 的 profile 可 以 通过 spring.profiles.active 属 性 进行 
设置 〈 通 常会 通过 名 为 SPRING_PROFILES_ACTIVE 的 环境 变量 进行 设 
置 》。 


类 似 的 ， 要 提供 面 癌 特定 应 用 和 profile 的 属性 ，Config Server 本 纺 
也 没有 太 多 需要 做 的 。 真 正比 较 重 要 的 是 ， 这 些 属性 在 文 择 Git 仓 库 中 
该 如 何 进行 存储 。 


14.4.1 提供 特定 应 用 的 属性 


按照 我 们 之 前 的 讨论 ， 使 用 Config Server 的 好 处 之 一 就 是 我 们 可 以 
让 应 用 中 的 所 有 微服 务 共 孚 通用 的 配置 属性 。 尽 官 如此， 有 些 属 性 可 能 
旦 东 个 服务 特有 的 ， 不 需要 《或 者 不 应 该 ) 与 所 有 的 服务 共 圣 。 


除了 共享 配置 之 外 ，Config Server 还 能 管理 面向 特定 应 用 的 配置 属 
性 。 要 实现 这 一 点 ， 需 要 将 配置 文件 的 名 称 命 名 为 该 应 用 
spring.application.name 属 性 的 值 。 


在 第 13 章 中 ， 我 们 使 用 spring.application.name 属 性 为 微服 务 提供 了 
一 个 名 称 ， 将 会 注册 到 Eureka 中 。 相 同 的 属性 也 可 以 被 配置 客 尸 问 用 来 
在 Config Server 中 识别 目 届 ， 这 样 Config Server 就 能 提供 该 应 用 特有 的 
配置 。 


例如 ， 在 Taco Cloud 应 用 中 ， 我 们 将 应 用 拆 分 成 了 多 个 微服 务 ， 分 
别 古 ingredient-service、order-service、taco-service 和 user-service， 我 们 可 
以 在 每 个 服务 的 Spring.application.name 属 性 中 指定 它 的 名 称 。 然 后 ， 我 
们 束 可 以 根据 各 个 服务 的 名 称 在 Config Server 的 Git 后 闪 创 建 对 应 的 配置 
YAML 文 件 ， 比 如 ingredient-service.yml、order-service.yml、taco- 
service.yml 和 user-service.yml。 图 14.3 为 Gogs Web 应 用 中 配置 仓库 的 文 
件 截 图 。 


不 官 服 务 应 用 的 名 称 是 什么 ， 所 有 有 的 应 用 都 会 接收 来 日 
application.yml 允 件 的 配置 。 但 是 ， 在 问 Config Server 及 起 请 求 的 时 候 ， 
每 个 服务 应 用 的 Spring.application.name 的 属性 值 会 一 同 发 送 〈 作 为 请 求 
路 径 的 第 一 部 分 ) ， 如 果 和 存在 逻 配 的 属性 文件 ， 那 么 该 文件 中 的 属性 将 


会 一 并 返回 。 如 末 application.yml 中 通用 的 属性 与 特定 应 用 配置 文件 中 
的 属性 出 现 重 复 ， 那 么 特定 应 用 的 属性 会 优先 生效 。 


需要 注意 的 是 ， 尽 管 岁 14.3 显 示 的 是 YAML 配 置 文件 ， 实 际 上 ， 如 
果 在 Git 仓 库 中 存放 properties 文 件 ， 同 样 的 规则 依然 有 效 。 
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图 14.3 ”应 用 特定 的 配置 文件 会 根据 每 个 应 用 的 spring.application.name 属 性 进行 命名 


14.4.2 ”提供 来 目 profile 的 属性 


在 第 5 半 中 ， 在 编写 配置 属性 时 ， 我 们 曾经 看 到 过 利用 Spring profile 
实现 特定 的 属性 只 有 在 给 定 profile 处 于 激活 状态 时 才 生 效 。Spring Cloud 
Config Server 采 用 与 单个 Spring Boot 应 用 完全 相同 的 方式 ， 提 供 了 对 特 
定 profile 属 性 的 支持 ， 包 括 : 


。 提供 特定 profile 的 “.properties” 或 YAML 文 件 ， 比 如 名 为 application- 


production.yml 的 配置 文件 ; 
。 在 一 个 YAML 文 件 中 提供 多 个 profile 配 置 组 ， 它 们 之 则 以 “---” 和 
Spring.profiles 分 割 开 。 


假设 我 们 要 通过 Config Server 为 应 用 所 有 的 微服 务 共 享 Eureka 配 
置 ， 现 在 它 只 引用 了 一 个 Eureka 开 发 实例 ， 对 于 开发 环境 来 说 是 很 不 错 
的 。 如 果 服 务 要 在 生产 环境 运行 ， 那 么 我 们 可 能 想 要 将 它 配置 成 引用 多 


个 Eureka 节 点 。 


另外 ， 尽 管 我 们 在 开发 环境 的 配置 中 将 server.port 属 性 设置 成 了 0， 
但 是 服务 在 部 闭 到 生产 环境 的 时 候 ， 每 个 服务 可 能 会 运行 到 独立 的 容器 
中 ， 容 器 将 8080 症 口 映射 到 外 部 的 端口 ， 这 样 束 需 要 所 有 的 应 用 都 监听 
8080 端 口 。 


借助 profile， 我 们 可 以 声明 多 个 配置 。 际 了 已经 推 庆 到 Config 
Server Git 后 端的 默认 application.yml 文 件 之 外 ， 我 们 还 可 以 推送 另外 一 
个 名 为 application-production.yml 的 YAMEL 文 件 ， 如 下 上 所 示 : 


server : 
port: 8080 


eureka: 
client: 
service-url: 
defaultZone: http://eurekal:8761/eureka/,http://eureka2:8761/eureka/ 





在 应 用 从 Config Server 获 取 配 置信 息 的 时 候 ，Config Server 会 识别 
哪个 profile 处 于 激活 状态 《位 于 请 求 路 径 的 第 二 部 分 ) 。 如 末 活 跃 
profile 古 production， 那 么 两 个 属性 集 (application.yml 和 application- 


production.yml) 都 将 会 返回 ， 并 且 application- production.yml 中 的 属性 
会 优先 于 application.yml 中 的 默认 属性 。 图 14.4 为 后 辣 Git 仓 库 的 显示 效 
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图 14.4 


我 们 还 可 以 使 用 同样 的 命名 约定 指定 


Fu 


特定 profile 的 配置 文件 在 命名 时 后 级 与 激活 profile 的 名 称 相 同 


适用 于 特定 应 用 且 特 定 profile 
的 属性 ， 也 就 十 将 属性 文件 命名 为 应 用 名 加 中 划 线 再 加 profile 名 的 形 


例如 ， 我 们 想 要 为 名 为 ingredient- -ServVice 的 应 用 设置 属性 ， 而 且 这 
些 属性 只 有 当 production profile 处 于 激活 状态 时 才 有 效 。 在 这 种 场景 
下 ， 名 为 ingredient-service-production.yml 的 文件 可 以 包含 特定 应 用 且 特 


定 profile 的 属性 ， 如 图 14.5 所 示 。 
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图 14.5 ”配置 文件 可 以 适用 于 特定 应 用 有 旦 特定 profile 的 属性 


对 于 特定 profile 的 属性 ， 在 后 端 Git 仓 库 中 ， 我 们 也 可 以 使 用 相同 命 
名 约定 的 properties 文 件 来 代替 YAML。 在 YAML 文 件 中 ， 我 们 可 以 将 特 
定 profile 的 属性 和 稚 认 profile 的 属性 放 到 同一 个 文件 中 ， 中 间 使 用 3 个 中 
划 线 和 spring.profiles 进 行 分 割 ， 相 关内 容 我 们 在 第 5 革 已 经 学 习 过 了 。 


14.5 ”保持 配置 属性 的 私密 性 


Config Server 提 供 的 大 多 数 配 置 可 能 并 不 是 私密 的 。 但 是， 我 们 可 
能 需要 Config Server 提 供 一 些 包 含 敏感 信息 的 属性 ， 比 如 密码 或 安全 
token， 在 后 端 仓 库 中 ， 它 们 最 好 保持 私密 。 


Config Server 提 供 了 两 种 方式 来 支持 私密 的 配置 属性 。 


。 在 Git 和 仓储 的 属性 文件 中 使 用 加 密 后 的 值 。 


。 使 用 HashiCorp Vault 作为 Config Server 的 后 痛 存 储 ， 补 苑 《或 茶 
代 ) Git。 


我 们 将 会 依次 看 一 下 这 两 种 方案 是 如 何 与 Config Server 组 合 使 用 你 
证 配置 属性 私宅 性 的 。 自 完 ， 我 们 看 一 下 如 何在 Git 后 问 中 号 入 加 密 的 
属性 。 


14.5.1 在 Git 中 加 密 属 性 


除了 提供 非 加 密 值 以 外 ，Config Server 也 可 以 借助 存储 在 Git 中 的 属 
性 文件 提供 加 密 值 。 处 理 存储 在 Git 中 的 加 密 数 据 的 关键 在 于 一 个 秘 钠 
(key) ， 即 加 密 秘 铀 (encryption key) 。 


为 了 局 用 加 密 属 性 功能 ， 我 们 使 用 一 个 加 密 秘 铀 来 配置 Config 
Server， 在 将 属性 值 提 供给 客户 问 应 用 之 前 ，Config Server 要 使 用 这 个 
秘 钥 对 属性 值 进 行 解密 。Config Server 支 持 对 称 秘 钥 和 非 对 称 秘 钥 。 
设置 对 称 秘 铀 ， 我 们 可 以 在 Config Server 目 己 的 配置 中 将 encrypt. 
性 设置 为 加 密 和 解密 秘 钥 的 值 : 


encrypt: 
key: s3cr3t 


很 重要 的 一 点 需要 注意 ， 这 个 属性 要 设置 到 bootstrap 配 置 中 〈( 例 
如 ，bootstrap.properties 或 bootstrap.yml) 。 这 样 的 话 ， 在 目 动 配置 功能 
局 用 Config Server 之 前 ， 这 个 属性 就 会 加 载 和 局 用 。 


为 了 更 加 安全 一 些 ， 我 们 可 以 让 Config Server 使 用 非 对 称 的 RSA 秘 


钥 对 或 引用 一 个 keystore。 要 创建 这 样 的 秘 铀 ， 我 们 可 以 使 用 keytool 命 
令 行 工 具 : 


keytool -genkeypair -alias tacokey -keyalg RSA \ 


-dname “CN=Web Server,OU=Unit,0=Organization,L=City,S=State,C=US" AN 
-keypass s3cr3t -keystore keystore.jks -storepass 13tm31n 





这 样 形成 的 keystore 会 写 入 到 名 为 keystore.jks 的 文件 中 。 我 们 可 以 将 
这 个 keystore.jks 文 件 放 到 文件 系统 中 或 者 放 到 应 用 本 喘 。 不 管 使 用 哪 种 
方式 ， 我 们 都 需要 在 Config Server 的 bootstrap.yml 文 件 中 配置 keystore 的 
位 置 和 插 证 信息 。 


注意 : 为 了 在 Config Server 中 使 用 加 密 功 能 ， 我 们 需要 要 安 
减 Java Cryptography Extensions Unlimited Strength 宋 略 文 件 。 参 
见 Oracle 的 Java SE 页 面 了 解 详细 信息 。 





例如 ， 假 设 我 们 要 将 keystore 打 包 到 应 用 本 丑 ， 将 其 放 到 类 路 和 任 的 
根 目 录 下 ， 那 么 我 们 可 以 配置 如 下 的 属性 ， 让 Config Server 使 用 议 
keystore: 
encrypt: 


key-store: 
alias: tacokey 


location: classpath:/keystore.jJks 
password: 13tm31n 
secret: s3cr3t 





秘 乌 和 keystore 吏 绪 之 后 ， 我 们 需要 对 霖 些 数 据 进行 加 黎 。Config 


Server 骏 露 了 一 个 %encrypt" 桨 口 会 帮助 我 们 实现 该 功能 。 我 们 需要 做 的 
就 是 提交 一 个 POST 请 求 到 ”encrypt” 端 点 ， 其 中 包括 要 加 密 的 数据 。 例 
如 ， 我 们 要 加 密 连 接 至 MongoDB 数 据 库 的 密码 。 借 助 curl， 我 们 可 以 按 
照 如 下 的 方式 加 密 密 公 


$ curl localhost:8888/encrypt -d "s3cr3tP455werd" 
93912a666a7f3co4e811b5df9a3cf6e1f63850cdcd4aa692cf5a3f7e1662fab7 


在 提交 POST 请 求 之 后 ， 我 们 会 接收 到 一 个 加 密 的 值 作为 啊 应 。 接 
下 来 ， 需 要 做 的 束 是 复制 这 个 值 并 煌 贴 到 Git 仓 库 托 管 的 配置 文件 中 。 


为 了 设置 MongoDB， 在 Git 仓 库 的 application.yml 文 件 中 添加 
spring.data.mongodb. password 属 性 : 


spring: 
data: 


mongodb: 
password: '{cipher}93912a6686a7f3ce@4e811b5df9a3cf6e1f63850... 





需要 注意 ，Sspring.data.mongodb.password 被 一 个 单 插 亏 (') 括 了 起 
来 ， 并 且 带 有 {cipher} 前 级 。 这 样 就 会 告诉 Config Server， 这 是 一 个 加 密 
的 值 ， 而 不 是 简单 的 未 加 密 值 。 


在 将 这 个 变更 提交 并 推 运 到 Git 仓 库 中 的 application.yml 文 件 之 后 ， 
Config Server 束 可 以 对 外 提供 加 等 的 属性 了 。 如 果 要 实际 看 一 下 ， 束 使 
用 curl 命 令 伪 装 成 Config Server 的 客户 疹 : 





$ curl localhost:8888/application/default | jq 
{ 


"Name”™: "app',， 
"profiles": | 


“Label : null, 


"version": “464adfd43485182e4e0af08c2aaaa64d2f78c4cf ， 
“State : null, 


"propertySources": | 


“name : "http://localhost:160806/tacocloud/tacocloudconfig/ 
application.yml",， 
"source": 1{ 
"spring.data.mongodb.password": "s3cr3tP455werd" 





我 们 可 以 看 到 ，spring.data.mongodb.password 的 值 是 以 解密 后 的 形 
式 提供 的 。 默 认 情 况 下 ，Config Server 提 供 的 所 有 加 密 值 只 是 在 后 端 Git 
仓库 中 处 于 加 答 的 状态 ， 它 们 在 对 外 提供 之 前 会 解密 。 这 意味 看 ， 消 费 
这 个 配置 的 客户 新 应 用 并 不 需要 任何 特殊 的 代码 和 配置 束 能 接收 Git 中 
已 加 和 密 的 属性 。 


如 果 你 想 要 让 Config Server 以 未 解密 的 形式 对 外 提供 加 密 属性 ， 那 
么 可 以 将 Spring.cloud.config.server.encrypt.enabled 属 性 设置 为 false: 


Spring : 
cloud: 
config: 
server: 


2it: 

uri: http://localhost:160806/tacocloud/tacocloud-config 
encrypt: 

enabled: false 





这 样 导 致 的 结果 束 是 Config Server 在 提供 所 有 的 属性 值 的 时 候 完 全 
按照 Git 仓 库 设 置 的 样子 进行 及 送 ， 包 括 已 加密 的 属性 值 。 我 们 再 雇 伪 


装 成 一 个 客户 站， 利用 curl 命 令 展示 茶 用 解密 的 效果 : 


$ curl localhost:8888/application/default | jq 
{ 


"propertySources": | 


"name": "http://localhost:160806/tacocloud/tacocloudconfig/ 
application.yml",， 
"source": 1{ 
"spring.data.mongodb.password": "{cipher}AQA4JeVhf2cRXW...”" 





当然 ， 如 果 客户 端 接收 到 了 未 解密 的 属性 值 ， 那 么 客户 端 需 要 自行 


管 可 以 通过 Config Server 在 Git 中 保存 已 加 签 的 私密 信息 ， 但 是 我 
们 可 看 到 加 人 并 不 是 Git 的 原生 特性 。 它 需要 我 们 目 己 对 与 入 Git 仓 库 
的 数据 进行 加 密 。 为 外， 除非 将 解密 的 任务 推 给 Config Server 的 客户 闹 
应 用 ， 否 则 对 于 任何 请 求 配置 的 客户 端 ，Config Server API 对 外 提供 的 
私密 dn 的 形式 。 我 们 接 下 来 看 一 下 为 一 个 Config Server 
后 病 方 宁 ， 它 能 够 只 同 己 授权 的 用 尸 提 供 私密 信 息 


14.5.2 ”在 Vault 中 存储 私密 信息 
HashiCorp Vault 古 一 个 私密 管 理工 具 。 这 意味 着 与 Git 相 比 ，Vault 


的 核心 特性 就 是 原生 地 人 处理 私密 信息 。 对 于 敏感 的 配置 数据 ，Vault 是 
一 个 更 有 吸引 力 的 Config Server 后 端 文 撑 方 案 。 


为 了 开始 使 用 Vault， 我 们 需要 参考 Vault Web 站 点 的 安装 指南 下 载 
并 安装 vault 命 令 行 工 具 。 在 本 小 节 中 ， 我 们 将 会 使 用 vault 命 令 管 理 私密 
言 息 和 启动 Vault 服 务 器 。 


启动 Vault 服 务 器 


在 使 用 Config Server 写 入 和 对 外 提供 私密 信息 之 前 ， 我 们 需要 局 动 
一 个 Vault 服 务 磊 。 对 于 我 们 来 讲 ， 最 人 简 蛙 的 方式 束 是 在 开发 模式 下 使 
用 如 下 的 命令 局 动 服务 器 : 


$ vault server -dev -dev-root-token-id=roottoken 


$ export VAULT _ADDR='http://127.9.6.1:8266， 
$ vault status 





第 一 条 命令 会 在 开发 模式 下 局 动 一 个 Vault 服 务 硕 ， 其 中 根 
token (root token) 的 ID 为 roottoken。 顾 名 思 义 ， 开 及 模式 意味 看 它 是 一 
个 更 简单 但 并 不 完全 安全 的 Vault 运 行 时 。 它 不 应 该 在 生产 环境 中 使 
用 ,但 是 在 开 友 的 工作 流程 中 ， 这 种 使 用 Vault 的 方式 会 非常 便利 。 


注意 : Vault 是 一 个 功能 完备 且 健 壮 的 私密 管理 工具 。 
开 友 模式 下 的 简单 使 用 之 外 ， 本 草 没 有 尽 够 的 遍 幅 完整 介绍 


Vault 服 务 右 的 运行 。 我 强烈 建议 你 在 笠 试 生产 环境 中 使 用 Vault 
之 前 ， 通 过 阅读 Vau 文 档 来 更 详细 地 了解 Vault。 





对 Vault 服 务 器 的 所 有 访问 都 需要 问 服务 颖 提供 一 个 token。 根 token 


征 一 个 管理 token， 这 意味 独 除了 其 他 功 能 之 外 ， 写 允许 我 们 创建 其 他 
的 token。 它 还 能 够 用 于 谈 取 和 与 入 私密 信息 。 如 果 在 开 肥 模式 局 动 服 
务 器 的 时 候 未 指定 根 token， 那 么 Vault 服 务 器 会 为 我 们 创建 一 个 token 并 
在 局 动 的 时 候 写 入 日 志 中 。 为 了 便于 使 用 ， 建 议 将 根 token 设 置 成 一 个 
易于 记忆 的 仁 ， 比 如 roottoken。 


开发 模式 的 服务 器 局 动 之 后 ， 它 将 会 监听 本 地 机 器 的 8200 端 口 。 上 所 
以 ， 要 让 vault 命 令 行 知 道 Vault 服 务 如 在 什么 地 方 ， 设 置 VAULT_ADDR 
环境 变量 是 非常 重要 的 ， 这 也 是 上 述 代码 片段 第 二 行 所 做 的 事情 。 


最 后 ，vVault status 命 令 会 校 验 之 前 的 两 条 命令 是 人 否 已 经 按照 预期 运 
行 。 你 大 致 会 看 到 接 述 Vault 服 务 占 的 6 个 属性 ， 包 括 Vault 是 合 密 闭 ( 
开发 模式 下 ， 它 不 应 该 处 于 密闭 状态 )〉。 


Ft 


使 用 Vault 0.10.0 或 之 后 的 版 本 的 话 ，Vault 与 Config Server 协 作 使 用 
之 前 还 有 其 他 的 两 条 命令 需要 执行 。Vault 和 运行 方式 的 一 些 变更 会 导致 
一 个 标准 的 私密 后 山 与 Config Server 不 若 容 。 以 下 两 个 命令 会 壬 狐 创 建 
名 为 secret 的 后 六 ， 以 碰 容 Config Server: 


$ vault secrets disable secret 
$ vault secrets enable -path=secret kv 

如 果 使 用 更 早 版 本 的 Vault， 就 不 需要 这 些 步骤 。 
与 入 私密 信息 到 Vault 中 


借助 vault 命 令 ， 可 以 很 容易 将 私密 信息 写 入 Vault 中 。 例 如 ， 假 设 


我 们 想 要 将 访问 MongoDB 的 密码 (也 就 是 
spring.data.mongodb.password ) 存储 到 Vault 中 ， 而 不 是 存储 到 Git 里 面 ， 


就 可 以 通过 vault 命 令 完 成 : 


$ vault write secret/application spring.data.mongodb.password=s3cr3t 


图 14.6 拆 分 了 vault write 命令 ， 阐 述 每 个 组 成 部 分 在 将 私密 信息 与 入 
Vault 的 过 程 中 扮演 了 什么 角色 。 


“secret” 后 端 私密 信息 的 key 


$ vault write secret/application spring.data.mongodb.password=s3cr3t 


执行 写 入 私密 信息 的 路 径 私密 信息 的 值 





图 14.6 ”通过 vault 命 令 将 私密 信息 写 入 Vault 


现在 ， 我 们 最 需要 关注 的 束 是 私密 信息 的 路 径 、key 和 值 。 私 密 信 
轧 的 路 径 就 像 文件 系统 中 的 路 径 那 样 ， 人 允许 我 们 将 相关 的 私 答 信息 放 到 
一 个 给 定 的 路 径 中 ， 而 将 其 他 的 私密 信息 放 到 不 同 的 路 径 中 。 路 径 的 前 
缀 “secret/” 用 来 识别 Vault 后 端 ， 在 这 里 使 用 了 一 个 key-value 的 后 端 ， 名 


为 “secret”。 


私密 信息 的 key 和 值 古 我 们 实际 要 写 入 Vault 的 内 容 。 当 Contfig 
Server 要 对 外 提供 已 号 入 的 私密 信息 时 ， 很 重要 的 一 点 在 于 私 冤 信息 的 
key 要 和 配置 属性 保持 一 致 。 


我 们 可 以 使 用 vault read 命 令 校 验 私密 信息 是 否 已 经 写 入 Vault 中 : 


上 vault read secret/application | 


Key Value 


refresh interval 768h 
spring.data.mongodb .password s3cr3t 





在 将 私密 信息 写 入 到 指定 路 径 的 时 候 ， 需 要 注意 每 次 往 给 定 路 径 中 
写 入 时 都 会 履 冰 之 前 在 该 路 径 下 与 入 的 私 敬 信息。 例如， 假设 我 们 还 想 
要 往 Vault 的 上 述 路 径 中 写 入 MongoDB 有 用户 名 ， 我 们 不 能 简单 地 写 入 
Spring.data.mongodb.username secret 私 窗 信 息 本 里 ， 如 果 这 样 做 就 会 导致 
spring.data.mongodb.password 私 密 信 息 丢 失 。 我 们 需要 同时 将 这 两 个 属 
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% vault write secret/application \ 


spring.data.mongodb.password=s3cr3t \ 
spring.data.mongodb.username=tacocloud 





现在 ， 我 们 已 经 往 Vault 中 写 入 了 一 些 私密 信息 。 接 下 来 ， 我 们 看 
一 下 如 何 让 Vault 作 为 Config Server 的 后 端 届 性 源 。 


在 Config Server 中 局 用 Vault 后 闪 


为 了 将 Vault 洪 加 为 Config Server 的 后 病 ， 我 们 全 少 和 需要 将 Vault 深 加 
为 激活 的 profile。 在 Config Server 的 application.yml 文 件 中 ， 将 会 如 下 所 


一 和 


和 仆 : 


Spring : 
profiles: 


active: 
- Vault 
- git 





如 上 所 示 ，vault 和 git profile 均 处 于 激活 状态 ， 允 许 Config Server 同 


时 从 Vault 和 Git 获 取 配 置 。 一 般 而 言 ， 我 们 会 将 敏感 的 配置 属性 写 入 
Vault， 对 于 不 再 要 私密 性 的 属性 则 继续 使 用 Git 作 为 后 中。 如 琳 你 硕 望 
将 所 有 配置 都 与 到 Vault 中 或 者 没有 必要 使 用 Git 后 瘦 ， 那 么 可 以 将 


Spring.profiles.active 设 置 为 vault， 完 全 放弃 Git 后 端 。 


默认 情况 下 ，Config Server 会 假定 Vault 运 行 在 localhost 并 监听 8200 
端口 。 但 是 ， 我 们 可 以 在 Config Server 的 配置 中 修改 这 种 默认 行为 ， 如 
下 所 示 : 


spring: 
cloud: 
config: 
server : 
2it: 
uri: http://localhost:160806/tacocloud/tacocloud-config 


order: 2 
vault: 
host: vault.tacocloud.com 
port: 82060 
scheme: https 
order: 1 





Config Server 对 Vault 的 默认 假定 都 可 以 通过 
spring.cloud.config.server.vault.* 相 关 的 属性 重 与 。 在 这 里 ， 我 们 告诉 
Config Server，Vault 的 API 可 以 通过 https://vault.tacocloud.com:8200 来 访 
问 O 


注意 ， 我 们 保留 了 Git 配 置 ， 假 定 Vault 和 Git 分 担 了 提供 配置 相关 的 
职员 。order 属 性 表明 Vault 提 供 的 私 窜 属性 要 优先 于 Git 提 供 的 属性 。 


在 配置 完 Config Server 使 用 Vault 作 为 后 病 之 后 ， 我 们 可 以 使 用 curl 


命令 伪装 成 一 个 客户 端 尝试 一 下 ; 


[habuma :habuma]% curl localhost:8888/application/default | jq 

{ 
"timestamp": "206018-64-29T23:33:22.275+6880"， 
"status": 4060, 


"error": "Bad Request ， 
"message": “Missing required header: X-Config-Token', 
"path": "/application/default" 





喘 ， 不 ! 似乎 出 现 问 题 了 。 实 际 上 ， 这 个 错误 表明 Config Server 提 
供 来 目 Vault 的 私密 信息 ， 但 古 请 求 中 没有 包含 Vault token。 


很 午 要 的 一 点 需要 注意 ， 对 Vault 的 所 有 请 求 都 要 包含 一 个 X-Vault- 
Token 头 信息 。 我 们 不 会 在 Config Server 本 身 中 配置 这 个 token， 而 是 让 
每 个 Config Server 客 户 山 在 癌 Config Server 发 送 请 求 的 时 候 在 请 求 中 包 
含 X-Config-Token 尖 信息 。Config Server 会 接收 到 X-Config-Token 汰 信 
娠 ， 然 后 将 其 转换 成 发 送 给 Vault 的 X-Vault-Token 状 信息 。 


我 们 可 以 看 到 ， 因 为 在 请 求 中 缺少 这 个 token， 所 以 Config Server 拒 
绝 提 供 任何 属性 ， 甚 至 连 Git 中 的 属性 都 不 可 用 了， 因为 在 骏 十 私密 的 
信息 之 前 需要 一 个 token。 这 是 组 合 使 用 Vault 和 和 Git 的 一 个 有 趣 的 副 作 
用 ， 除 非 提 供 一 个 合法 的 token， 人 否则 连 Git 属 性 都 会 被 Config Server 则 接 
强 藏 。 


我 们 可 以 再 笠 试 一 下 ， 在 请 求 中 洪 加 一 个 X-Config-Token 尖 信息 : 


$ curl localhost:8888/application/default 


-H"X-Config-Token: roottoken" | jq 





请 求 中 的 这 个 X-Config-Token 头 信息 应 该 会 产生 更 好 的 结果 ， 啊 应 
中 将 会 包含 我 们 写 入 到 Vault 中 的 私密 信息 。 这 里 给 出 的 token 是 在 我 们 
以 开发 模式 局 动 Vault 的 时 候 设 置 的 根 token， 但 实际 上 Vault 服 务 器 创建 
的 所 有 人 合法、 未 过 期 且 具 有 访问 Vault 私 密 后 端的 token 都 是 可 以 的 。 


在 Config Server 和 客户 六 设 置 Vault token 


显然 ， 在 每 个 微服 务 中 ， 我 们 不 能 使 用 curl 来 指定 消费 Config Server 
属性 的 token。 相 反 ， 我 们 应 访 在 服务 应 用 的 本 地 配置 中 这 加 一 点 配置 
= 自 


百 /NA : 


Spring : 


cloud: 
config: 
token: roottoken 





spring.cloud.config.token 属 性 会 告诉 Config Server 客 户 端 在 每 次 回 
Config Server 用 送 请 求 的 时 候 都 要 市 上 给 定 的 token。 这 个 属性 必须 设置 
到 应 用 的 本 地 配置 中 (而 不 能 存放 到 Config Server 的 Git 或 Vault 中 )， 
Config Server 才 能 够 将 其 传递 到 Vault 上 ， 从 而 访问 私密 属性 。 


写 入 特定 应 用 和 特定 profile 的 私密 信息 


在 为 Config Server 提 供 服 务 的 时 候 ， 写 入 application 路 径 的 属性 运用 
于 所 有 的 应 用 ， 不 管 它们 的 名 字 是 什么 。 如 果 我 们 想 要 写 入 针对 给 定 应 
用 的 私密 属性 ， 残 需要 将 路 径 中 的 application 部 分 改 成 应 用 的 名 称 。 例 
如 ， 如 下 的 vault write 命令 会 为 名 为 ingredient-service 的 应 用 〈 通 过 其 


spring.application.name 属 性 指定 ) 写 入 专 有 的 私密 信息 : 


$ vault write secret/ingredient-service \ 
spring.data.mongodb.password=s3cr3t 


类 似 的 ， 如 果 我 们 不 指定 profile， 写 入 Vault 的 私密 信 筷 束 会 成 为 默 
认 profile 属 性 的 一 部 分 。 也 残 是 说 ， 不 管 哪个 profile 处 于 激活 状态 ， 客 
尸 并 都 能 收 到 这 些 私密 信息 。 我 们 可 能 想 要 将 私密 信息 写 入 到 特定 的 


profile 中 ， 如 下 所 示 : 


% vault write secret/application,production \ 


spring.data.mongodb.password=s3cr3t \ 
spring.data.mongodb.username=tacocloud 





这 种 方式 写 入 的 私密 信息 只 对 激活 profile 为 production 的 应 用 有 效 。 


14.6 ”在 运行 时 刷新 配置 属性 


在 编写 本 章 的 时 候 ， 我 正在 一 架 飞 机 上 ， 因 为 维护 问题 ， 飞 机 被 重 
新 拉 回 了 登 机 口 。 情 况 并 不 严重 ， 你 正在 读本 章 的 内 容 ， 就 说 明 机 械 工 
程 师 的 工作 完成 得 还 是 很 令 人 满意 的 。 即 便 如 此 ， 关 于 飞机 维护 ， 最 有 
意思 的 事情 是 它 要求 飞 机 必须 要 在 地 面 上 。 如 果 飞 机 正在 飞行 ， 那 么 能 
做 的 事情 整 太 少 了 。 


相 比 之 下 ， 在 《星球 大 战 》 (Star Wars) 电影 中 ， 如 果 Luke 
Skywalker 或 Poe Dameron 的 X 训 战机 需要 维护 ， 舰 载 机 械 机 右 人 (mech 
droid) 就 可 以 派 上 用 场 了 ， 即 使 X 踊 战机 正在 作战 ， 它 也 可 以 开展 工 
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传统 上 ， 应 用 程序 维护 ， 包 括 配 置 更 改 ， 午 需要 重新 部 普 或 全 少 重 
新 局 动 应 用 。 可 以 次 ， 由 于 缺少 一 个 “机 械 机 部 人 ?来 调整 哪 介 是 了 最 小 的 
配置 属性 ， 因 此 我 们 每 次 都 需要 将 应 用 程序 拉 回 “和 釜 机 口 ?。 这 对 云 原 生 
应 用 来 说 生 不 可 接受 的 。 我 们 和 希望 能 够 动态 地 更 改 配置 属性 ， 而 不 需要 
关闭 应 用 程序 。 


幸运 的 是 ，Spring Cloud Config Server 能 够 刷新 正在 运行 的 应 用 程 
序 的 配置 属性 ， 而 不 需要 人 停机。 一旦 变更 推送 到 文 撑 的 Git 仓 库 或 Vault 
私密 仓库 ， 应 用 中 的 每 个 微服 务 束 部 可 以 立即 通过 以 下 两 种 方式 的 茶 一 
种 进行 刷新 。 


。 于 动 刷 新 : Config Server 和 客户 病 局 用 一 个 特殊 的 “/actuator/refresh” 闹 
点 ， 对 每 个 服务 的 这 个 端点 发 送 HTTP POST 请 求 将 会 强制 配置 客户 
疹 从 Config Server 的 后 闯 检 索 最 新 的 配置 。 

目 动 刷新 : Git 仓 库 上 的 提交 hook 会 触 肥 所 有 Config Server 客 户 问 服 
务 的 刷新 操作 。 这 涉及 Spring Cloud 的 另 一 个 项 目 ， 名 为 Spring 
Cloud Bus， 它 能 够 用 于 Config Server 及 其 客户 端 之 间 的 通信 。 


每 种 方案 都 有 其 优 点 和 缺点 。 于 动 刷 新 能 够 更 狂 确 地 控制 服务 何 时 
更 新 最 新 配置 ， 但 是 它 需 要 问 每 个 做 服务 实例 及 送 一 个 HITP 请 求 。 目 
动 更 新 能 够 让 应 用 中 的 每 个 微服 务 即 时 使 用 最 新 的 配置 ， 但 它 是 由 配置 
仓库 的 提交 目 动 触 友 的 ， 对 于 有 些 项 目 来 说 过 于 危险。 


我 们 接 下 来 看 一 下 这 两 种 方案 ， 然 后 你 就 可 以 目 行 选择 哪 种 方式 更 
适合 你 的 项 目 了 。 


14.6.1 手动 刷新 配置 属性 


在 第 16 章 中 ， 我 们 将 会 介绍 Spring Boot Actuator。 它 是 Spring Boot 
的 基本 元 系 之 一 ， 能 够 探查 应 用 运行 时 的 状况 并 且 允 许 对 运行 时 进行 一 
些 有 限 的 操作 ， 比 如 修改 日 志 级 别 。 现 在 先 看 一 个 特殊 的 Actuator 特 
性 ， 只 有 配置 为 Spring Cloud Config Server 客 户 站 的 应 用 ， 这 个 特性 才 
有 效 。 


当 我 们 将 应 用 设置 为 Config Server 和 客户 端的 时 候 ， 日 动 配置 功能 会 
配置 一 个 特殊 的 Actuator 闸 点 ， 用 来 刷新 配置 属性 。 为 了 使 用 该 病 护 ， 
在 项 日 的 构建 文件 中 除了 Config Client 依 赖 ， 我 们 还 需要 添加 Actuator 
starter 依 赖 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-actuator</artifactId> 
</dependency> 





我 们 可 以 猜 到 ， 这 项 依赖 也 可 以 在 Spring Initializr 中 通过 选中 
Actuator 复 选 框 添加 进来 。 


在 Config Server 客 户 端 应 用 中 添加 Actuator 之 后 ， 我 们 可 以 在 任意 时 
间 发 送 HTTP POST 请 求 到 “actuatorrefresh”， 通 知 它 从 后 端 仓 库 刷 新 配 
置 属性 。 


我 们 看 一 下 它 是 如 何 实现 的 。 假 设 我 们 有 一 个 市 有 
@ConfigurationProperties 注 解 的 类 ， 名 为 GreetingProps: 


@ConfigurationProperties(prefix="greeting") 
QComponent 
public class GreetingProps { 

private String message; 


public String getMessage() { 


return message,; 


} 


public void setMessage(String message) { 
this.message = message; 
} 
} 





另外， 我 们 可 以 编写 一 个 控制 右 类 。GreetingProps 会 注入 其 中 ， 妆 
它 在 处 理 GET 请 求 时 ， 人 返回 message 属 性 的 值 : 
QRestController 
public class GreetingController { 
private final GreetingProps props; 
public GreetingController(GreetingProps props) { 


this.props = props; 


} 


@QGetMapping("/hello") 
public String message() { 
return props.getMessage(); 


} 


} 





在 我 们 的 Git 配 置 仓库 中 有 一 个 application.yml 文 件 ， 含 有 如 下 的 属 
性 设置 : 


greeting: 
message: Hello World! 


Config Server 和 这 个 简单 的 hello-world 配 置 客户 端 运行 起 来 之 后 ， 


我 们 对 “hello” 发 送 HTTP GET 请 求 ， 将 会 产生 如 下 的 响应 : 


$ curl localhost:8060806/hello 
He lo Worldl 


现在 ， 我 们 对 Config Server 和 hello-world 都 不 进行 重启 ， 而 是 修改 
application.yml 文 件 并 推送 至 后 端 Git 仓 库 ， 这 样 greeting.message 属 性 将 
让 


greeting: 
message: Hiya folks! 


即便 在 Git 中 配置 已 经 发 生变 化 ， 如 果 我 们 发 送 GET 请 求 到 hello- 
world 应 用 ， 得 到 的 结果 依然 是 “Hello World”* 啊 应 。 但 是 ， 我 们 可 以 对 
刷新 端点 发 送 一 个 POST 请 求 ， 强 制 使 其 刷新 : 


$ curl localhost:53419/actuator/refresh -XxX POST 





[ “config.client.version","greeting.message" | 


注意 ， 啊 应 中 包含 一 个 JSON 数 组 ， 列 出 了 发 生变 更 的 属性 名 。 这 
个 数组 包 合 greeting.message 属 性 ， 还 包 售 config.client.version 属 性 (当前 
配置 对 应 的 Git 提 交 的 哈 希 值 ) 的 变化 。 因 为 现在 的 配置 基于 一 个 狐 的 
Git 握 交 ， 上 所 以 每 当 后 端的 配置 仓库 有 变化 时 ， 这 个 值 都 会 跟 独 变化 。 


POST 请 求 的 啊 应 告诉 我 们 greeting.message 已 经 发 生变 化 了 。 但 
旦 ， 真 正 的 证 据 还 是 要 徘 再 次 同 “%hello” 路 径 及 送 GET 请 求 : 


$ curl localhost:8060806/hello 
Hiya folks! 


无 须 重 启 应 用 ， 甚 至 无 须 重 启 Config Server， 应 用 现在 就 能 向 我 们 
提供 greeting.message 属 性 的 全 新 值 。 


如 末 我 们 能 够 完全 控制 何 时 对 配置 属性 进行 更 新 ， 那 
么 %actuatorrefresh” 谢 点 是 很 不 铺 的 选择 。 如 末 我 们 的 应 用 由 多 个 微服 
务 组 成 《可 能 每 个 服务 部 有 多 个 实例 ) ， 那 么 将 配置 传播 到 所 有 服务 可 
能 是 一 项 非常 乏味 的 工作 。 接 下 来 ， 我 们 看 一 下 如 何 一 次 性 地 将 配置 变 
更 上 自动 用 到 所 有 服务 上 。 


14.6.2 ” 目 动 刷新 配置 属性 


Config Server 能 够 借助 名 为 Spring Cloud Bus 的 Spring Cloud 项 目 将 配 
置 变 更 自动 通知 到 每 个 客户 闹 ， 作 为 手动 刷新 应 用 中 每 个 Config Server 
客户 问 属 性 的 符 代 方案 。 图 14.7 阐 述 了 它 是 如 何 运 行 的 。 
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图 14.7 Config Server 与 Spring Cloud Bus 能 够 对 应 用 广播 变更 (应 用 会 在 属性 发 生变 化 的 时 候 ， 
目 动 刷 新 它们 的 属性 》 


可 以 简要 概括 图 14.7 中 的 属性 刷新 流程 。 


。 在 配置 Git 仓 库 上 创建 一 个 webhook， 当 Git 仓 库 有 任何 变化 《比如 
所 有 的 推送 ) 时 ， 都 会 通知 Config Server。 很 多 的 Git 实 现 都 文 持 
webhook， 比 如 GitHub、GitLab、Bitbucket 和 Gogs。 

。 Config Server 会 对 webhook POST 请 求 做 出 啊 应 ， 借 助 菜 种 消 奶 代理 
以 消 轧 的 方式 广播 该 变更 。 

。 每 个 Config Server 各 户 奖 应 用 订阅 讼 通知 ， 对 通知 消息 做 出 啊 应 ， 

也 残 是 会 使 用 Config Server 中 的 新 属性 值 刷 新 它们 的 环境 。 


这 样 做 的 结果 束 是 ， 在 配置 属性 变更 推送 到 后 端的 Git 仓 库 之 后 ， 
所 有 的 Config Server 冤 户 闹 应 用 能 够 立即 获取 最 狐 的 配置 属性 值 。 


在 使 用 Config Server 的 目 动 属 性 刷新 功能 时 ， 会 有 多 个 部 件 在 发 挥 
作用 。 我 们 回顾 一 下 要 做 的 变更 ， 这 样 对 需要 做 的 事情 会 有 一 个 整体 的 
本 解 。 

。 我 们 需要 有 一 个 消息 代理 ， 用 来 处 理 Config Server 及 其 客户 问 之 间 
的 消息 传递 ， 可 以 选择 RabbitMQ 或 Kafka。 

。 在 后 疹 Git 仓 库 上 需要 创建 一 个 webhook， 将 各 种 变更 通知 给 Config 
Server。 

。 Config Server 需 要 启用 Config Server 监 控 依 赖 (提供 了 人 处理 Git 仓 库 
webhook 请 求 的 病 点 〉 以 及 RabbitMQ 或 KafkafhjSpring Cloud Stream 
依 顿 〈 用 于 发 布 属性 变更 消息 给 代理 ) 。 

。 除非 消 明 代理 在 本 地 按照 献 认 设置 运行 ， 耕 则 ， 我 们 要 在 Config 
Server 及 其 所 有 的 客户 闹 上 配置 连接 至 代理 的 详细 信息 。 

。 每 个 Config Server 的 客户 闹 应 用 需要 Spring Cloud Bus 依 赖 。 


假设 预先 需要 的 消息 代理 《不管 是 RabbitMQ、Kafka， 还 是 你 选择 
的 其 他 方案 ) 已 经 处 于 运行 状态 ， 并 且 为 传送 属性 变更 消息 做 好 了 堆 
备 ， 我 们 首先 从 将 属性 变更 应 用 于 Config Server 开 始 ， 让 和 它 处 理 
webhook 的 更 新 请 求 。 


创建 webhook 


很 多 Git 服 务 都 支持 创建 webhook， 从 而 能 够 将 Git 仓 库 的 变更 信息 
通知 给 应 用 ， 这 些 变 更 包括 推送 。 不 同 实 现 之 间 创 建 webhook 的 操作 有 
所 和 寺 异 ， 我 们 很 难 对 它们 一 一 摘 述 。 在 这 里 ， 我 会 介绍 如 何 为 Gogs 仓 库 
创建 webhook。 


我 选择 Gogs 的 原因 在 于 它 非常 易于 在 本 地 运行 ， 并 昌文 持 将 
webhook POST 用 到 本 地 运行 的 应 用 上 (对 于 GitHub 来 说 ， 这 非常 难以 
实现 ) 。 同 时 ， 在 Gogs 上 创建 webhook 的 过 程 与 GitHub 几 乎 完全 相同 ， 
因此 摘 述 Gogs 的 过 程 能 够 间接 让 你 知道 为 GitHub 创 建 webhook 都 需要 哪 


些 步 又 。 


首先 ， 在 Web 浏 览 磺 中 访问 配置 仓库 并 点 击 Settings 链 接 ， 如 图 14.8 
所 示 。 〈GitHub 上 Settings 链 接 的 位 置 略 有 天 异 ， 但 是 它们 的 外 观 很 相 
似 。) 
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图 14.8 ”在 Gogs 或 GitHub 上 点 击 Settings 开 始 创 建 webhook 


这 会 将 我 们 市 到 仓库 的 设置 页 面 ， 在 左 侧 包 含 了 一 个 设置 分 类 的 这 
蛙 。 在 来 时 中 选择 Webhooks， 将 会 出 现 如 图 14.9 所 示 的 页 面 。 
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图 14.9 ”Webhooks 页 面 中 的 Add Webhook 按 钮 会 打开 创建 webhook 的 表单 


在 Webhooks 设 置 页 面 ， 上 点击 Add Webhook 按 钮 ， 在 Gogs 中 会 生成 
一 个 下 拉 列 表 ， 用 来 选择 不 同类 型 的 webhook。 选 择 Gogs 选 项 ， 如 图 
14.9 所 示 。 这 样 ， 我 们 会 看 到 一 个 创建 新 webhook 的 表单 ， 如 图 14.10 所 
示 呈 。 


Add Webhook 表 单 有 多 个 输入 域 ， 重 要 的 是 Payload URL 和 Content 


Type。 我 们 马上 将 会 配置 Config Server 来 处 理 webhook 的 POST 请 求 。 在 
实现 该 功能 的 时 候 ，Config Server 将 会 在 %monitor” 路 径 下 处 理 webhook 
请 求 。 因 此 ， 我 们 需要 将 Payload URL 输 入 域 设 置 成 引用 Config Server 

有 时“/monitor”* 闹 点 的 URL。 因 为 我 是 在 一 个 Docker 容 器 中 运行 Gogs 的 ， 
所 以 在 图 14.10 中 将 URL 设 置 成 http://host.docker.internal:8888/monitor， 

它 的 域名 为 host.docker.internal。 这 个 域名 让 Gog 服 务 右 能 够 跨越 容 帮 的 
边界 访问 宿主 机 器 上 的 Config Serverl 。 
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Collaboration form-urlencoded, XML, etc). More information can be found in our Webhooks Guide. 
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图 14.10 ”创建 webhook 时 需要 指定 Config Server 的 “/monitor”"”URL 和 JSON 载 克 


我 还 将 Content Type 输入 域 设置 成 了 application/json。 这 一 点 非常 重 
要 ， 因 为 Config Server 的 “monitor” 闻 点 并 不 文 持 Content Type 有 的 为 一 个 


选项 application/Xx-www- form-urlencoded。 


如 果 设 置 Secret 输 入 域 ， 就 可 以 在 webhook POST 请 求 中 新 增 一 个 名 
为 X-Gogs-Signature 〈 在 GitHub 中 名 为 X-Hub-Signature) 的 头 信息 ， 包 
含 给 定 私密 信息 的 HMAC-SHA256 摘 要 〈 在 GitHub 中 是 HMAC- 
SHA1) 。 此 时 ，Config Server 的 “monitor” 端 点 并 不 识别 这 个 签名 头 信 
思 ， 因 此 我 们 可 以 将 这 个 输入 域 设 置 为 至 


最 后 ， 我 们 只 关心 配置 仓库 的 推送 请 求 ， 另 外 ， 我 们 当然 布 望 这 个 
webhook 处 于 活跃 状态 ， 所 以 需要 确保 Just the push event 单 选 枉 和 Active 
复 选 框 处 于 选中 状态 。 扣 击 表单 奔 部 的 Add Webhook 按 钮 ，webhook 束 
创建 完成 了 。 每 当 仓库 有 推送 的 时 候 ， 束 会 同 Config Server 友 送 POST 请 


现在 ， 我 们 必须 要 启用 Config Server 的 “/monitor” 端 点 来 处 理 这 


企 Config Server 中 处 理 webhook 更 新 


要 局 用 Config Server 的 “monitor” 闪 点 非 第 简单 ， 我 们 只 需 添 加 
spring-cloud-config-monitor 依 赖 到 Config Server 的 配置 文件 即 可 。 在 
MavenH 肘 pom.xml 文 件 中 ， 如 下 的 依赖 就 会 完成 该 项 工作 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-config-monitor</artifactId> 
</dependency> 


这 项 依赖 添加 完成 之 后 ， 自 动 配 置 功能 会 发 挥 作用 ， 从 而 局 
用 %monitor” 痪 点。 但 是 ， 除 非 Config Server 本 里 有 广播 变更 通知 的 方 
法 ， 人 否则 不 会 市 来 任何 好 处 。 为 了 实现 这 一 点 ， 我 们 需要 还 加 对 Spring 
Cloud Stream 的 依 赖 。 


Spring Cloud Stream 是 男 一 个 Spring Cloud 项 目 。 借 助 它 ， 我 们 能 够 
创建 通过 的 层 绑 定 机 制 通信 的 服务 ， 这 种 通 rsa nd 
Kafka。 服 务 在 编写 的 时 候 并 不 会 天 心 如何 使 用 这 些 通 信 机 制 ， 只 是 接 
受 流 中 的 数据 ， 对 其 进行 处 理 ， 并 返回 到 流 中 ， 由 下 游 的 服务 继续 处 
js 


“monitor” 端 点 使 用 Spring Cloud Stream 发 布 通知 消息 给 参与 的 
Config Server 客 户 闹 。 为 了 避免 价 编 人 特定 的 消 明 实现， 监控 幽会 作为 
Spring Cloud Stream 的 产 ， 友 布 消息 到 流 中 并 让 底层 的 绑 定 机 制 处 理 消 
轧 有 友 达 的 特定 功能 


如 来 使 用 RabbitMQ， 束 需要 将 Spring Cloud Stream RabbitMQ 绑 定 
依赖 添加 到 Config Server 的 构建 文件 中 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-stream-rabbit</artifactId> 
</dependency> 





如 末 你 更 喜欢 Kafka， 那 么 需要 这 加 如 下 的 Spring Cloud Stream 
Kafka 依 颊 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-stream-kafka</artifactId> 
</dependency> 





依赖 准备 就 绪 之 后 ，Config Server 儿 平 就 可 以 参与 属性 自动 刷新 功 
能 了 。 实 际 上 ， 如 果 RabbitMQ 或 Kafka 在 本 地 运行 并 且 使 用 默认 配置 ， 
Config Server 就 已 经 可 以 运行 了 。 如 果 消 明代 理 在 其 他 地 方 运行 ， 而 不 
征 在 localhost， 或 者 使 用 了 非 默认 病 口 ， 驻 或 者 我 们 修改 了 访问 代理 的 
凭证 信息 ， 就 需要 在 Config Server 本 身 的 配置 中 添加 一 些 属性 了 。 


如 果 采 用 RabbitMQ 绑 定 ， 那 么 application.yml 中 的 如 下 条 目 可 以 用 
来 重 写 默 认 信 : 


Spring : 
rabbitmq: 
host: rabbit.tacocloud.conm 


port: 5672 
username: tacocloud 
password: s3cr3t 





虽然 我 们 在 这 里 设置 了 所 有 的 属性 ， 但 是 在 你 的 RabbitMQ 代 理 中 
只 需要 设置 与 于 认 值 不 同 的 属性 即 可 。 


如 朱 使 用 Kafka， 可 以 使 用 基 似 的 属性 : 


Spring : 
kafka: 
bootstrap-servers: 


- kafka.tacocloud .com:9092 
- kafka.tacocloud .com:9093 
- kafka.tacocloud .com:9094 





你 会 发 现 ， 这 些 属性 来 源 于 第 8 章 我 们 学 习 Kafka 消 息 时 的 配置 。 实 


际 上 ， 配 置 自动 刷新 功能 的 RabbitMQ 和 Kafka 后 端 与 在 Spring 中 使 用 代 
理 的 其 他 场景 非常 相似 。 


创建 Gogs 的 退 知 提取 上 


对 于 每 个 Git 实 现 来 说 ，webhook POST 请 求 所 携带 的 内 容 会 有 所 不 
同 。 所 以 ， 对 于 “/monitor* 问 点 来 说 ， 很 重要 的 一 点 就 古 在 处 理 webhook 
POST 请 求 时 能 够 理解 不 同 的 数据 格式 。 在 舌 后 ，“/monitor” 闹 点 会 有 一 
组 组 件 来 检查 POST 请 求 ， 试 图 弄 清楚 请 求 来 日 哪 种 Git 服 务 细 ， 然 后 将 
请 求 数据 映 射 为 通用 的 通知 类 型 ， 并 友 运 至 每 个 客户 病 。 


Config Server 对 多 个 流行 的 Git 实 现 提 供 了 开 箱 即 用 的 支持 ， 比 如 
GitHub、GitLab 和 Bitbucket。 如 末 你 使 用 其 中 的 杀 一 个 实现 ， 那 么 不 需 
要 任何 额外 的 操作 。 在 我 编写 本 书 的 时 低 ，Gogs 还 没有 得 到 官方 文 
持 趾 。 因 此 ， 使 用 Gogs 作 为 Git 实 现 的 话 ， 我 们 需要 在 项 目 中 提供 一 个 
Gogs 的 通知 握 取 需 


程序 清单 14.1 为 Taco Cloud 集 成 Gogs 时 我 所 使 用 的 通知 提取 器 


程序 清单 14.1 ”Gogs 的 通知 提取 器 实现 





package tacos.gogs; 

Import java.util.Collection, 

import JjJava.util.HashSet; 

Import java.util.Map; 

import Java.util.Set; 

Import org.springframework.cloud.config.monitor.PropertyPathNotification; 

import 
org.springframework.cloud.config.monitor.PropertyPathNotificationExtr 

acCtonr ; 

import org.springframework.core.Ordered; 


import org.sprIngframework.core.annotation.O0rder; 
import org.springframework.stereotype.Component; 
import org.springframework.util.MultiValueMap; 


QComponent 

@Order(Ordered.LOWEST PRECEDENCE - 3060) 

public class GogsPropertyPathNotificationExtractor 
implements PropertyPathNotificationExtractor { 


QOverride 
public PropertyPathNotification extract( 
MultiValueMapx<String, String> headers, 
Map<String, Object> request) { 
if ("push".equals(headers.getFirst("X-Gogs-Event"))) { 
if (request.get("commits") instanceof Collection) { 
Set<String> paths = new HashSet<>() ; 
@SuppressWarnings("unchecked") 
Collection<Map<String, Object>> commits = 
(Collection<Map<String, Object>>) request 
.2et("commits"); 
for (Map<String, Object> commit : commits) { 
addAllPaths(paths, commit, "added"); 
addAllPaths(paths, commit, "removed"); 
addAllPaths(paths, commit, "modified"); 
} 
if (lpaths.isEmpty()) { 
return new PropertyPathNotification( 
paths .toArray(new String[6]) ); 


} 
} 
} 


return null; 


} 


private void addAllPaths(Set<String> paths, 
Map<String, Object> commit, 
String name) { 
@SuppressWarnings("unchecked") 
Collection<String> files = 
(Collection<String>) commit.get(name); 
if (files != null) { 
paths.addAll(files); 
} 
} 


GogsPropertyPathNotificationExtractor 如 何 运 行 的 细节 与 我 们 的 讨论 
没有 太 大 关系 ， 并 且 在 Spring Cloud Config Server 内 置 对 Gogs 的 文 持 之 
后 ， 束 更 加 无 天 崇 要 了 。 所 以 ， 我 不 会 对 它 进行 过 多 的 介绍 ， 将 它 放 在 
这 里 只 是 为 了 让 你 在 使 用 Gogs 的 时 候 ， 可 以 作为 参考 。 


在 Config Server 的 各 户 妆 中 局 用 上 自动 刷新 


在 Config Server 各 户 痪 司 用 属性 的 目 劲 刷新 比 Config Server 本 里 会 
更 加 简单 。 我 们 需要 添加 一 项 依赖 : 


<dependencyy> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-bus-amqp</artifactId> 
</dependency> 





这 样 会 添加 AMQP 〈 如 RabbitMQ ) Spring Cloud Bus starter 到 构建 文 
Ts 


如 采 使 用 Kafka， 丈 需要 诬 加 如 下 的 依赖 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-bus-kafka</artifactId> 
</dependency> 





对 应 的 Spring Cloud Bus starter 人 准备 刺 弹 之 后 ， 局 动 应 用 的 时 候 ， 目 
动 配置 功能 束 会 友 挥 作用 ， 应 用 会 日 动 将 目 己 乡 定 到 本 地 运行 的 
RabbitMQ 代 理 或 Kafka 集 群 上 。 如 果 你 的 RabbitMQ 或 Kafka 在 其 他 地 方 
运行 ， 那 么 我 们 需要 在 每 个 客户 站 应 用 上 像 Config Server 本 里 那样 配置 
它们 的 详细 信息 。 


Config Server 及 其 客户 端 都 配置 成 了 文 持 目 动 刷新 。 将 它们 局 动 起 
来 ， 并 对 application.yml 做 一 下 修改 〈 任 意 修 改 都 可 以 ) ， 当 将 该 文件 
提交 至 Git 仓 库 的 时 候 ， 我 们 会 立即 看 到 它 在 客户 端 应 用 中 生效 。 


14.7 小 结 


。 Spring Cloud Config Server 提 供 了 中 心 化 的 配置 数据 产 ， 能 够 用 于 
微服 务 架 构 应 用 中 的 所 有 微服 务 。 

。 Config Server 提 供 的 属性 是 通过 后 端的 Git 或 Vault 仓 库 维 护 的 。 

除了 暴露 给 所 有 Config Server 客 户 端的 全 局 属性 ，Config Server 还 

能 提供 特定 profile 和 特定 应 用 的 配置 。 

敏感 数据 能 够 剑 持 私密 ， 这 可 以 在 后 端 Git 仓 库 中 通过 对 其 进行 加 

密 来 实现 ， 也 可 以 通过 在 Vault 后 端 存储 私密 信息 来 实现 。 

。 Config Server 各 户 痪 能 够 信 助 手动 或 目 劲 刷新 得 到 新 的 属性 ， 前 者 
通过 Actuator 妆 点 来 实现 ， 后 者 通过 Spring Cloud Bus 和 Git 
webhooks 来 实现 。 





[1] ” GitHub 没有 可 选 webhook 的 下 拉 列 表 。 在 点 击 Add Webhook 按 钮 之 
后 ， 会 直接 出 现 创 建 webhook 的 表单 。 


[2] 在 Docker 容 颖 中 。l1ocalhost 指 的 是 容 右 本 里 ， 和 而 不 是 Docker 答 主 
机 L。 


[3] 作者 给 Config Server 项 目 提交 了 一 个 支持 Gogs 的 pull request。 在 它 
合并 进去 之 后 ， 本 书 的 这 个 章 市 束 没 有 必要 关注 了 了。 目前， 作者 的 这 个 
pull request 经 修改 后 ， 已 经 合并 到 了 Config Server 中 。 一 一 译 者 注 


第 15 章 ”处 理 失 败 和 延迟 


本 草 内 容 : 


汤 路 织 模 式 人 简介 


使 用 Hystrix 处 理 失败 和 延迟 


监控 断路 大 


聚合 断路 瘟 的 指标 





15.1 理解 断路 器 模式 


汤 跤 右 模 式 是 随 关 Michael Nygard 的 Release It! (第 2 版 ，Pragmatic 
Bookshelf，2018) 一 书 流行 起 来 的 ， 解 决 了 我 们 所 编写 的 代码 可 能 会 失 
败 的 问题 。 很 重要 的 一 点 在 于 ， 即 便 是 失败 ， 它 也 能 够 优雅 地 失败 。 这 
个 强大 的 模式 在 微服 务 坏 境 中 会 更 加 关键， 因为 在 这 种 坏 境 下 避免 跨 调 
用 堆栈 产生 级 联 失 败 非常 重要 。 


相对 来 讲 ， 上 断路 规模 式 的 理念 很 向 单 ， 非 营 英 似 于 现实 世界 中 的 电 


路 断路 项， 这 也 是 它 得 名 的 由 来 。 在 电路 断路 厚 中 ， 当 开关 处 于 闭合 位 
曾 时 ， 电 流 能 够 流 过 断路 禹 ， 为 房间 中 的 电灯 、 电 视 、 电 脑 和 其 他 设备 
供电 。 如 末 线 路 中 出 现 故 障 ， 比 如 功率 又 增 ， 靳 路 强 束 会 打开 ， 在 电流 
损坏 电子 设备 或 房屋 失火 之 前 切断 电流 。 


与 之 类 似 ， 软 件 中 的 断路 融 起 初 会 处 于 关闭 状态 ， 允 许 进 行 方法 的 
调用 。 如 条 因 为 菏 种 原因 ， 方 法 调用 失败 了 《比如 时 间 超 出 了 定义 的 败 
值 ) ， 上 断路 夫 束 会 打开 ， 融 不 会 对 失败 的 方法 再 执行 调用 了 。 软 件 断 路 
器 的 区 别 在 于 它 提供 了 后 备 〈fallback) 行为 和 自 校正 功能 。 


如 条 被 保护 的 方法 在 给 定 的 失败 国 值 内 有 友 生 了 失败， 那么 可 以 调用 
一 个 后 备 方法 代 丛 它 的 位 置 。 在 断路 硕 处 于 打开 状态 之 后 ， 几 乎 始终 都 
会 调用 后 备 方法 。 处 于 打开 状态 的 断路 器 偶尔 会 进入 半 开 状态 ， 并 淮 试 
调用 友 生 失 败 的 方法 : 如 末 依 然 失败 ， 断 路 奉承 恢复 为 打开 状态 ， 如 朱 
调用 成 功 ， 它 会 认为 问题 已 经 解雇 ， 上 断路 硕 会 问 到 闭合 状态。 图 15.1 曾 
述 了 软件 断路 颖 的 流程 。 


成 功 调用 /后 备 






失败 /后 备 可 
( 低 于 阔 值 ) 下 


图 15.1 断路 套 模 式 能 够 实现 优雅 的 失败 处 理 


我 们 可 以 将 断路 上 硕 想象 成 一 个 更 加 强大 的 try/catch。 闭 合 的 断路 恬 
类 似 于 try 代 人 码 块 ， 而 后 备 方法 类 似 于 catch 代 人 码 块 。 与 try/catch 个 同 的 地 
方 在 于 ， 嘱 路 需 非 党 和 镶 能 ， 当 预期 方法 频带 失败 时 它 会 经 过 预期 方法 ， 
始终 调用 后 备 方法 。 


按照 我 的 曾 述 ， 上 断路 硕 是 应 用 到 方法 上 的 。 这 梓 ， 在 给 定 的 一 个 微 
服务 中 ， 很 容易 融 能 达到 数 十 个 “其 全 更 多 ) 断路 葵 。 诀 定 在 代码 的 什 
么 地 方 声明 其 路 左 其 实 束 是 识别 哪些 方法 易于 出 现 失败 。 如 下 的 几 关 方 
法 肯定 是 添加 断路 夯 的 首选 。 


。 调用 REST 的 方法 : 这 些 方 法 可 能 会 因为 远程 服务 不 可 用 或 者 返回 
HTTP 500 响 应 而 失败 。 
。 执行 数据 库 查 询 的 方法 : 这 些 方法 可 能 会 因为 数据 库 不 啊 应 或 者 模 
式 变 更 人 破坏 了 应 用 而 导致 失败 。 
。 可 能 会 比较 慢 的 方法 : 它们 不 一 定 会 失败 ， 但 是 如 果 耗 费 太 长 时 间 
才能 完成 工作 就 可 能 会 被 视 为 失败 。 
最 后 一 项 强调 了 除 处 理 故 障 之 外 断路 器 的 男 一 项 收益 。 在 微服 务 
中 ， 延 人 迟 也 是 非常 重要 的 ， 某 个 执行 缓慢 的 微服 务 不 能 拖 慢 整个 微服 务 
的 性 能 ， 避 免 上 游 的 服务 产生 级 联 延迟 是 非常 重要 的 。 


我 们 可 以 看 到 ， 呆 路 硕 贷 式 是 在 代 担 中 优雅 处 理 故 隐 和 延迟 的 强大 
方法 。 那 么 该 如 何 将 断路 硕 用 到 我 们 的 代码 中 呢 ? 竺 运 的 是 ，Netflix 开 
着 项 目 退 过 Hystrix 为 我 们 提供 了 舍 柔 。 


Netflix Hystrix 是 断路 器 模式 的 Java 实 现 。 简 而 言 之 ，Hystrix 电 路 器 
实现 为 一 个 切面 ， 会 在 目标 方法 发 生 失 败 的 时 候 触 发 后 备 方 法 。 为 了 实 
现 断 路 右 模 式 ， 这 个 切面 还 会 跟踪 目标 方法 失败 的 频 读 ; 如 果 失 败 率 超 
过 了 茶 个 国 什 ， 那 么 所 有 的 请 求 都 会 转 及 全 后 备 方法 。 


关于 Hystrix 名 称 的 一 点 逸事 


当 Netflix 的 开发 人 员 为 他 们 的 靳 路 颖 实现 起 名 字 的 时 候 ， 他 们 想 要 
这 个 名 字 能 够 体现 出 需要 提供 的 弹性 、 防 御 能 力 和 容错 能 力 。 最 终 ， 他 
们 选择 了 Hystrix (Hystrix 是 古代 坚 猪 的 一 种 ， 索 猪 是 一 种 能 够 使 用 长 刺 
进行 自卫 的 动物 ) 。 此 外 ， 正 如 Hystrix FAQ 中 所 解释 的 ， 这 是 一 个 听 
起 来 很 酷 的 名 称 。 当 我 们 在 15.3.1 小 节 中 三 看 Hystrix dashboard 时 ， 我 们 
束 会 在 项 目的 Logo 位 置 处 看 到 一 个 坚 猪 的 图 案 。 


Spring Cloud Netflix 包 含 对 Hystrix 的 支持 ， 提 供 了 一 个 人 简 蛙 的 编程 
模型 。Spring 和 Spring Boot 开 发 人 员 都 应 该 很 熟悉 这 个 模型 。 为 方法 洪 
加 @HystrixCommand 注 解 并 提供 一 个 后 备 方法 ， 束 可 以 为 该 方法 声明 朵 
路 器 。 下 面 让 我 们 看 看 如 何在 Taco Cloud 代 码 中 声明 断路 器 ， 从 而 优雅 
地 使 用 Hystrix 来 处 理 失 败 。 


15.2 声明 断路 融 


在 声明 断路 噩 之 前 ， 我 们 需要 琴 加 Spring Cloud Netflix Hystrix 
starter 依 赖 到 每 个 服务 的 构建 文件 中 。 在 Maven pom.xml 文 件 中 ， 依 赖 如 
下 所 示 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-netflix-hystrix</artifactId> 
</dependency> 





作为 Spring Cloud 人 套件 的 一 部 分 ， 我 们 需要 在 构建 文件 中 声明 Spring 
Cloud release train 的 依赖 常理。 在 我 编写 本 书 的 时 候 ， 最 新 的 release 
train 版 本 为 Finchley.SR1。 所 以 ， 应 该 将 Spring Cloud 的 版 本 设置 为 一 个 
属性 ， 如 下 的 条 目 应 该 出 现在 pom.xml 文 件 的 <dependencyManagement> 
代码 块 中 : 


<properties> 


<spring-cloud.version>Finchley.SR1</spring-cloud.version> 
</properties> 


<dependencyManagement> 
<dependencies> 
<dependency> 
<grouplId>org.springframework.cloud</groupId> 
<artifactId>spring-cloud-dependencies</artifactId> 
<«version>${spring-cloud.version}</version> 
<type>pom</type> 
<scope>import</scope> 
</dependency> 
</dependencies> 
</dependencyManagement> 


注意 : 在 创建 项 目的 时 候 ，starter 依 赖 也 可 以 在 Initializr 中 通 
过 名 为 Hystrix 的 复 选 框 来 进行 添加 。 如 有 果 使 用 Initializr 私 加 
Hvystrix 到 项 目的 构建 文件 中 ， 那 么 依赖 管理 代码 块 会 目 动 创建 。 





Hystrix starter 束 弹 之 后 ， 接 下 来 的 事情 束 是 局 用 Hystrix。 为 了 实现 
这 一 点 ， 我 们 可 以 在 应 用 的 主 配 置 类 上 六 加 @EnableHystrix。 例 如 ， 为 
了 在 配料 服务 上 启用 Hystrix， 我 们 可 以 按照 如 下 的 方式 为 
IngredientServiceApplication 湛 加 注解 : 


@SpringBootApplication 
@EnableHystrix 


public class IngredientServiceApplication { 





} 


这 样 ， 在 我 们 的 应 用 中 束 司 用 Hystrix 了 ， 也 束 症 味 着 声明 断路 噩 的 
所 有 准备 工作 都 做 完了 。 在 我 们 的 代码 中 还 没有 声明 任何 一 个 断路 天 ， 
这 时 @HystrixzCommand 注 解 莽 能 够 友 挥 作用 了 。 


任何 使 用 @HystrixzCommand 注 解 的 方法 都 会 为 其 声明 一 个 断路 霹 切 
面 。 例 如 ， 如 下 的 方法 使 用 文 持 负 载 均衡 的 RestTemplate 从 配料 服务 中 
锋 取 一 个 Ingredient 对 象 的 列表 : 


public Iterable<Ingredient> getAllIingredients() { 
ParameterizedTypeReference<List<Ingredient>> stringList = 
new ParameterizedTypeReference<List<Ingredient>>() {}; 


return rest.exchange(l 
"http://ingredient-service/ingredients", HttpMethod.GET, 
HttpEntity.EMPTY, stringList).getBody(); 





对 exchange() 的 调用 可 能 会 上 过 到 问题 。 如 果 Eureka 没 有 注册 名 为 
ingredient-service 的 服务 或 者 由 于 菏 种 原因 请 求 失 败 了 ， 那 么 将 会 抛 出 
RestClientException 〈 非 检查 型 异种 ) 。 因 为 开 利 没有 在 try/catch 代 人 码 块 
中 进行 处 理 ， 所 以 调用 者 必须 要 处 理 这 个 异 第。 如 果 调 用 者 不 处 理 ， 那 


么 它 将 党 看 调用 栈 往 上 抛 出 :如果 它 根本 没有 得 到 处 理 ， 那 么 这 个 错误 
会 级 联 到 所 有 上 游 微服 务 或 客户 病 


在 任何 应 用 中 ， 未 捕获 的 寞 第 都 古 一 项 艰巨 的 挑战 ， 在 做 服务 中 尤 
为 如 此 。 当 人 直到 失败 的 时 低 ， 短 服务 应 该 应 用 维 加 斯 规则 (Vegas 
Rule) : 在 微服 务 中 发 生 的 事情 ， 束 留 在 微服 务 中 。 在 
getAllingredients0) 方 法 上 声明 断路 需 将 会 满足 该 规则 。 


按照 最 少 的 要 求 ， 我 们 只 需要 为 该 方法 添加 @HystrixCommand 注 解 
并 为 其 提供 一 个 后 备 方法 即 可 。 首 先 ， 我 们 谎 加 @HystrixCommand 注 解 
到 getAllIngredientsO) 方 法 上 : 


@HystrixCommand(fallbackMethod="getDefaultIngredients") 
public Iterable<Ingredient> getAllIingredients() { 





人 


条 路 器 为 getAllIngredientsO0 提 供 了 失败 防护 ， 所 以 在 迪 到 失败 时 它 
是 安全 的 。 如 果 由 于 某 种 原因 getAllimngredientsO 抛 出 了 未 捕获 的 异 帝 ， 
么 断路 露 将 会 捕获 它们 并 将 方法 调用 重 定 同 到 名 为 
getDefaultIngredients() 的 方法 上 。 


你 可 以 让 后 备 方法 做 任何 事情 ， 但 是 它们 的 本 意 是 当 原 始 的 方法 无 
法 履行 职 贡 时 提供 后 备 行 为 。 后 备 行为 方法 的 唯一 规则 是 它们 要 与 原始 
方法 具有 相同 的 签名 《除了 方法 名 称 之 外 ) 。 


为 了 满足 该 要 求 ，getAllIngredients() 也 不 能 接受 任何 参数 并 要 返回 
List<Ingredient>。 如 下 的 getAllIngredients() 实 现 满足 该 规则 ， 并 且 返 回 


一 个 默认 的 配料 列表 : 


private Iterable<Ingredient> getDefaultIingredients() { 
List<Ingredient> ingredients = new ArrayList<>(); 
ingredients.add(new Ingredient( 
"FLTO", "Flour Tortilla", Ingredient.Type.WRAP)); 
ingredients.add(new Ingredient( 
"GRBF", "Ground Beef", Ingredient.Type.PROTEIN)); 


ingredients.add(new Ingredient( 
"CHED", "Shredded Cheddar", Ingredient.Type.CHEESE)); 
return ingredients; 





现在 ， 如 果 因 为 某 种 原因 导致 getAllIngredientsO0 失 败 ， 那 么 断路 器 
将 会 调用 备用 的 getDefaultImngredientsO0， 坑 用 者 将 会 接收 到 默认 的 配料 
列表 《尽管 非常 有 限 ) 。 


你 可 能 会 想 ， 如 末 备 用 方法 本 喘 有 上 断 路 天 又 会 怎样 呢 。 尽 管 按 照 我 
们 的 写法 ，getDefaultIngredients() 儿 平 不 vig 出 问题 ， 但 是 更 天 意思 
的 是 getDefaultIngredients() 可 能 会 有 潜在 的 失败 点 。 如 果 是 这 样 ， 那 么 
我 们 可 以 在 getDefaultImngredientsO0 上 还 加 @HystrixzCommand 注 解 并 提供 
男 一 个 备用 方法 。 实 际 上 ， 需 要 的 话 ， 我 们 可 以 堆积 任意 数量 的 备用 方 
法 。 唯 一 的 要 求 就 是 必须 要 在 后 备 方法 的 的 部 有 一 个 不 会 失败 的 方法 ， 
该 方法 不 需要 使 用 汤 路 如 


15.2.1 缓解 延迟 
断路 器 还 能 缓解 延迟 。 如 果 某 个 方法 需要 较 长 的 时 间 才 能 返回 ， 断 


路 替 会 将 它 设 置 为 超时 。 款 认 情 况 下 ， RAW 
的 方法 都 会 在 1 秒 之 后 超时 ， 并 调用 它们 所 声明 的 后 备 方法 。 这 意味 


看 ， 如 条 因为 茶 种 原因 配料 服务 啊 应 缓慢 ， 那 么 对 getAllIngredientsO) 调 
用 会 在 1 秒 之 后 超时 ， 而 且 会 调用 getDefaultIngredientsO 作 为 将 代 方 案 。 


1 秒 超时 是 一 个 合理 的 默认 值 ， 适 用 于 大 多 数 的 场景 。 我 们 也 可 以 
通过 Hystrix 命 令 属性 将 其 调整 为 更 大 或 更 小 的 限制 仁 。 设 置 Hystrix 命 令 
属性 可 以 通过 @HystrizCommand 注 解 的 commandProperties 属 性 来 实 
现 。commandProperties 属 性 是 一 个 或 多 个 @HystrixProperty 注 解 所 组 成 
的 数组 ， 指 定 了 要 设置 的 属性 名 和 值 "1。 


为 了 调整 断路 颖 的 超时 值 ， 我 们 需要 设置 Hystrix 命 令 属 性 
execution.isolation.thread.timeoutInMilliseconds。 例 如 ， 为 了 将 
getAllIngredients() 的 超时 时 间 更 加 严格 地 设置 为 0.5 秒 ， 那 么 我 们 可 以 将 
超时 设置 为 500， 如 下 所 示 : 


@HystrixCommand( 
fallbackMethod="getDefaultIingredients",， 
commandProperties={ 
@HystrixProperty( 
Name="execution.isolation.thread.timeoutInMilliseconds",， 
value="5060") 


}) 
public Iterable<Ingredient> getAllIingredients() { 


} 





这 里 设置 的 值 是 县 秒 数 。 如 果 我 们 希望 放松 限制 ， 那 么 可 以 将 其 设 
置 成 一 个 更 大 的 值 。 或 者 ， 如 果 你 认为 这 里 不 应 该 使 用 超时 功能 ， 那 么 
可 以 将 execution.timeout.enabled 属 性 设置 为 false， 耻 接 将 超时 功能 移 


除 : 


hystrixCommandt 


fallbackMethod="getDefaultIngredients",， 
commandProperties={ 
@HystrixProperty( 
name="execution.timeout.enabled",， 
value="false") 


}) 
public Iterable<Ingredient> getAllIingredients() { 


} 





将 execution.timeout.enabled 为 false 的 话 就 没有 延迟 防护 了 。 在 本 例 
中 ，getAllingredientsO) 方 法 不 管 是 耗 用 1 秒 、10 秒 还 是 30 分 钟 ， 它 都 不 会 
超时 。 这 可 能 会 导致 级 联 的 延迟 效果 ， 所 以 在 苯 用 执行 超时 的 时 候 要 非 
名 小 人 


15.2.2 ”管理 断路 器 的 闵 值 


堆 认 情况 下 ， 如 朱 断 路 套 傈 护 的 方法 调用 超过 20 次 ， 而 且 50% 以 上 
的 调用 在 10 秒 的 时 间 内 安生 失败 ， 那 么 断路 硕 吏 会 进入 打开 状态 。 所 有 
后 续 的 调用 都 将 会 由 后 备 方法 处 理 。 在 5 秒 之 后 ， 上 断路 器 进入 半 开 状 
态 ， 将 会 再 次 符 试 调用 原始 的 方法 。 


我 们 可 以 通过 设置 Hystrix 命 令 属性 调整 失败 和 重 弃 的 国 值 。 如 下 的 
命令 属性 将 会 影响 断路 占 的 行为 。 


。 circuitBreaker.requestVolumeThreshold: 在 给 定 的 时 间 范 围 内 ， 方 法 
应 议 梓 调用 的 识 数 。 

e circuitBreaker.errorThresholdPercentage: 在 给 定 的 时 间 范 围 内 ， 方 
法 调用 产生 失败 的 百分比 。 


。 metrics.rollingStats.timeInMilliseconds: 控制 请 求 量 和 错误 百分比 的 


滚动 时 间 周 期 。 

。 circuitBreaker.sleepWindowInMilliseconds: 处 于 打开 状态 的 断路 妖 
要 经 过 多 长 时 间 才 会 进入 半 开 状态 ， 进 入 半 开 状态 之 后 ， 将 会 再 次 
笑 试 失败 的 原始 方法 。 


如 果 在 metrics.rollingState.timeInMilliseconds 设 定 的 时 间 范 围 内 超出 
J circuitBreaker.requestVolumeThreshold 利 
circuitBreaker.errorThresholdPercentage 设 置 的 值 ， 那 么 断路 器 将 会 进入 
打开 状态 。 在 circuitBreaker.sleepWindowInMilliseconds 上 限定 的 时 间 沁 
内 ， 它 会 一 直 处 于 打开 状态 ， 在 此 之 后 将 进入 半 开 状态 ， 进 入 半 开 状态 
之 后 ， 将 会 再 次 疾 试 失败 的 原始 方法 。 


例如 ， 我 们 调整 失败 的 设置 ， 将 其 变更 为 在 20 秒 的 时 间 范 围 内 调用 
超过 30 次 且 失败 率 超过 25%。 为 了 实现 这 一 点 ， 我 们 需要 按照 如 下 的 广 


式 调 整 Hystrix 命 令 属 性 : 


@HystrixCommand( 
fallbackMethod="getDefaultIingredients",， 
commandProperties={ 

@HystrixProperty( 
name="circuitBreaker.requestVolumeThreshold",， 
value="30"), 

@HystrixProperty( 
name="circuitBreaker.errorThresholdPercentage",， 
value="25"), 

@HystrixProperty( 
name="metrics.rollingStats.timeInNnMilliseconds",， 
value="266860") 


}) 
public List<Ingredient> getAllIngredients() { 


Se 





} 


为 外 ， 我 们 还 决定 处 于 打开 状态 之 后 断路 卓 必 须 你 持 1 分 人 钟 ， 然 后 


才 进 入 半 开 状态 ， 那 么 我 们 还 需要 设置 
circuitBreaker.sleepWindowInMilliseconds 命 令 属 性 : 
@HystrixCommand( 


fallbackMethod="getDefaultIingredients",， 
commandProperties=f{ 


QHystrixProperty'( 
name="circuitBreaker.sleepWindowInNnMilliseconds",， 
value="60606860") 





除了 优雅 地 处 理 方法 调用 失败 和 延迟 之 外 ，Hvystrix 还 为 应 用 中 的 每 
个 断路 项 提供 了 一 个 指标 流 。 接 下 来 ， 我 们 看 一 下 如 何 通 过 Hystrix 沉 监 
控 司 用 Hystrix 功 能 的 应 用 的 监控 状况 。 


15.3 ”监控 失败 


每 当 断 路 可 保护 的 方法 被 调用 时 ， 它 虱 会 收集 一 些 调用 相关 的 数 
扬 ， 并 将 其 友 布 到 一 个 HTTP 流 中 ， 这 些 数 据 可 以 实时 监控 正在 运行 中 
的 应 用 的 健康 状况 。 在 每 个 断路 天 收集 的 数据 中 ，Hystrix 流 包括 如 下 内 


» 
AAAN 


合 : 


。 方法 伞 调 用 了 多 少 次 
。 调用 成 功 了 多 少 次 

。 后 各 方法 调用 了 多 少 次 
。 方法 超时 了 多 少 次 


Hystrix 流 是 由 Actuator 闪 点 提供 的 。 在 第 16 章 中 ， 我 们 会 更 详细 地 
讨论 Actuator， 现 在 只 需要 将 Actuator 依 赖 添加 a 到 所 有 服务 的 构建 文件 


中 ， 以 便于 启用 Hystrix 流 即 可 。 在 Maven pom.xml 文 件 中 ， 如 下 的 starter 
依赖 会 将 Actuator 添 加 到 项 目 中 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-actuator</artifactId> 
</dependency> 





Hvystrix 流 端点 会 通过 “%actuatorvhystrix.stream2” 路 径 对 外 其 露 。 默 认 
情况 下 ， 大 多 数 的 六 点 部 是 禁用 的 。 我 们 可 以 通过 在 每 个 应 用 的 
application.yml 父 件 中 添加 如 下 的 配置 局 用 Hystrix 闹 点: 


management: 
endpoints: 


web: 


exposure: 
include: hystrix.stream 





我 们 还 可 以 将 management:endpoints:web:exposure:include 属 性 放 到 
Config Server 对 外 提供 配置 属性 的 application.yml 文 件 中 ， 这 样 全 局 所 有 
的 服务 束 部 可 以 使 用 它 了 。 


应 用 局 动 之 后 ， 将 会 又 露 Hystrix 流 《这 个 流 可 以 被 任意 的 REST 闹 
点 消费 ) 。 在 编写 目 定 义 的 REST 闹 点 之 有 前， 我 们 需要 注意 HTTP 流 的 每 
个 条 目 部 包含 了 各 种 类 型 的 JSON 数 据 ， 客 户 新 需要 大 量 的 工作 才能 解 
析 这 些 数 据 。 尺 官 编写 目 定 义 的 Hystrix 流 展现 层 并 非 不 可 能 完成 的 任 
务 ， 但 是 在 花费 大 量 工夫 编写 自己 的 dashboard 之 前 我 们 可 以 考虑 一 下 使 
用 Hvystrix 的 dashboard 。 


15.3.1 Hystrix Dashboard 人 简介 


要 使 用 Hystrix Dashboard， 我 们 首先 创建 一 个 Spring Boot 凡 用 并 添 
加 对 Hystrix dashboard starter 的 依赖 。 如 果 使 用 Spring Boot Initializr 来 创 
建 项 目 ， 就 可 以 选择 Hystrix Dashboard 复 选 框 ; 和 否则， 我 们 需要 添加 如 
下 的 <dependency> 到 项 目的 Maven pom.xml 文 件 中 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-netflix-hystrix-dashboard</artifactId> 
</dependency> 





项 目 初始 化 之 后 ， 我 们 可 以 通过 为 主 配 置 类 添加 
@EnableHystrixDashboard 注 解 来 局 用 Hystrix dashboard: 
@SpringBootApplication 


@EnableHystrixDashboard 
public class HystrixDashboardApplication { 


public static void main(String[] args) { 
SpringApplication.run(HystrixDashboardApplication.class, args); 





在 开发 阶段 ， 我 们 可 能 会 让 Hystrix Dashboard 与 其 他 服务 一 起 在 本 
地 机 器 运行 ， 还 包括 Eureka 和 Config Server。 因 此 ， 为 了 避免 端口 冲 
突 ， 我 们 需要 为 Hystrix Dashboard 选 取 一 个 唯一 的 闹 口 。 在 DashboardVY 
用 的 application.yml 文 件 中 ， 我 们 可 以 将 server.port 设 置 成 任意 唯一 的 
值 ， 我 通 钊 会 将 其 设置 为 7979， 如 下 所 示 : 


server: 
port: 7979 


现在 ， 我 们 就 可 以 启动 Hystrix Dashboard 并 查看 其 效果 了 。 运 行 之 


后 ， 打 开 浏 览 器 并 访问 http://localhost:7979/hystrix， 我 们 将 会 看 到 如 图 
15.2 所 示 的 Hystrix Dashboard 主 页 。 
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图 15.2 ”Hystrix Dashboard 主 页 


关于 Hystrix Dashboard 主 页 ， 你 首先 会 注意 到 的 可 能 是 
logo (Hystrix 项 目的 卡通 坚 猪 吉祥 物 ) 。 要 俘 看 Hystrix 流 ， 我 们 需要 输 
入 某 个 服务 应 用 的 Hystrix 流 URL 到 文本 域 中 。 比 如 ， 配 料 服务 在 
localhost 运 行 并 且 监 昕 59896( 这 是 因为 将 server.port 设 置 成 了 0)， ， 那 么 
我 们 可 以 在 文本 框 中 输入 “http://localhost:59896/actuator/hystrix.stream”。 


在 Hystrix 演 监视 右 中 ， 我 们 可 以 设置 延 运 和 标题 。 延 运 的 默认 值 是 
2 秒 ， 指 的 是 轮 询 周期 的 间隔 ， 它 实际 上 会 延 绥 流 。 标 题 输入 域 的 值 会 
以 标题 的 形式 显示 在 监控 页 中 。 对 于 我 们 的 需求 来 说 ， 默 认 值 束 可 以 


了 。 


点 击 Monitor Stream 按 钮 ， 我 们 束 可 以 进入 Hystrix 流 的 监视 大 页 面 
了 ， 如 图 15.3 所 示 。 
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图 15.3 ”Hystrix 流 监控 页 面 会 显示 每 个 应 用 的 断路 占 指 标 


每 个 断路 器 都 会 显示 为 一 个 图 表 并 且 还 市 有 一 些 有 用 的 指标 数据 。 
图 15.3 中 只 显示 了 getAllIngredientsO 的 断路 硕 ， 因 为 到 目前 为 止 我 们 只 
定义 了 这 一 个 断路 右 。 


如 果 看 不 到 崭 跤 问 的 任何 图 表 ， 只 是 看 到 一 个 单词 “Loading”， 那 
么 可 能 是 靳 路 幽 方法 都 还 没有 侯 调 用 。 我 们 必须 回 服务 友 运 一 个 请 求 ， 
触 肥 断路 颖 你 护 该 方法 ， 这 样 方法 的 断路 颖 指标 才 会 避 示 在 Dashboard 
上 。 我 近 距 离 观 察 了 一 个 断路 右 的 监视 郝 《〈 见 图 15.4) ， 并 对 其 中 显示 
的 所 有 数据 都 进行 了 标注 。 
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图 15.4 ”每 个 断路 如 的 监视 占 部 提供 了 该 断路 占 当 前 状态 的 有 用 信息 





在 监视 器 中 ， 最 引 人 注 目的 是 左上 角 的 图 表 。 折 线 图 代表 了 指定 方 
法 过 去 两 分 钟 的 流量 ， 简 要 显示 了 该 方法 的 繁忙 情况 。 


折线 图 的 痛 景 是 一 个 大 小 和 闫 色 会 出 现 波动 的 圆 峰 。 圆 阐 的 大 小 表 
示 当 前 的 流量 ， 圆 峰 越 大 ， 沉 量 越 大 。 圆 峰 的 闫 色 表 示 它 的 健康 状况 : 
绿色 表示 健康 的 断路 桌 ， 员 色 表 示 侦 尔 友 生 故 障 的 断路 ， 红 色 表 示 故 
障 靳 跤 兹 。 


在 监视 郝 的 右上 角 ， 以 3 列 的 形式 显示 各 种 计数 器 。 在 最 左边 的 一 
列 中 ， 从 上 到 下 ， 第 一 个 数字 【绿色 一 一 在 本 书 的 电子 版 中 会 看 出 各 种 
颜色 ) 表示 当前 成 功 调用 的 数量 ， 第 二 个 数字 《〈 赣 色 ) 表示 短路 请 求 的 
数量 ， 最 后 一 个 数字 区 绿色 ) 表示 销 误 请 求 的 数量 。 中 间 一 列 电 示 超 
时 请 求 的 数量 《黄色 ) 、 线 程 池 拒 绝 的 数量 (紫色 )〉 和 失败 请 求 的 数量 
(红色 ) 。 第 三 列 显 示 过 去 10 秒 内 错误 的 百分率 。 


计数 器 下 面 有 两 个 数字 ， 代 表 每 秒 主机 和 集群 的 请 求 数量 。 这 两 个 


请 求 率 下 面 是 断路 器 的 状态 。 监 视 器 的 底部 显示 了 延迟 的 中 位 数 和 平均 
值 ， 以 及 第 90、99 和 99.5 百 分 位 的 延迟 。 


15.3.2 ”理解 Hystrix 的 线程 模型 


假设 某 个 方法 要 耗费 大 量 的 时 间 才 能 完成 其 任务 。 这 个 方法 可 能 回 
其 他 的 服务 发 起 了 HTTP 请 求 ， 而 该 服务 响应 很 慢 。 在 服务 响应 之 前 ， 
Hystrix 会 阻 罕 线程 ， 等 每 响应 。 


如 果 这 个 方法 执行 时 与 调用 者 在 同一 个 线程 上 下 文中 ， 那 么 调用 者 
将 会 一 直 在 这 个 长 时 间 运 行 的 方法 上 进行 等 每 。 男 外 ， 如 有 果 补 阻 暑 的 线 
程 来 自 一 组 数量 有 限 的 线程 集 ， 比 如 Tomcat 的 请 求 处 理 线程 ， 而 且 这 种 
情况 一 直 持 续 ， 那 么 当 所 有 线程 耗 尽 并 全 部 等 每 啊 应 时 ， 束 会 影响 到 可 
扩展 性 。 


为 了 避免 这 种 现象 ，Hystrix 会 为 每 项 依赖 〈 比 如， 市 有 一 个 或 多 个 
Hystrix 命 令 方 法 的 每 个 Spring bean) 指派 一 个 线程 池 。 当 Hystrix 命 令 调 
用 时 ， 和 将 会 在 来 目 Hystrix 托 管 的 线程 池 的 条 个 线程 中 执行 ， 这 样 会 将 
其 与 调用 者 线程 隅 离开 。 如 果 被 调用 的 方法 要 执行 较 长 时 间 ， 束 能 够 允 
许 调用 线程 不 用 一 直 等 每 ， 将 潜在 的 线程 耗 尽 隔离 在 Hystrix 托 省 的 线程 
闻 中 。 


你 可 能 会 肥 现 在 图 15.3 中 除了 断路 强 的 监视 右 外 ， 在 页 面 质 部 还 有 
另 一 个 监视 器 ， 位 于 “Thread Pools” 标 题 之 下 。 这 个 区 域 是 Hystrix 托 管 的 
每 个 线程 池 的 监视 普 。 图 15.5 展 示 了 一 个 线程 池 监 视 占 ， 并 对 其 中 的 数 


扼 进 行 了 标注 。 


圆圈 的 大 小 代表 当前 的 流 
量 ， 颜 色 代表 健康 状况 、、、 IngredientServicelmpl 
每 秒 的 请 求 数 
lost: 42.7/S 
Bon Sluster: 42.7/S 最 大 活跃 线程 
Active 0 Max Active 1 
排队 线程 一 一 >” QUeued 0 Executions 427 + 一 一 执行 次 数 
_ Pool Size 10 Queue Size 3D 如 程 队列 大 小 
线程 池 的 大 小 | 


图 15.5 ”线程 池 监 视 器 显示 Hystrix 托 绾 的 线程 池 的 重要 统计 信息 


与 断路 右 的 监视 如 类 似 ， 每 个 线程 池 监 视 帮 在 左上 角 痢 全 有 一 个 加 
立 。 圆 圈 的 六 小 和 颜色 代表 了 线程 池 的 活跃 状态 以 及 它 的 健康 状况 。 与 
潜 路 人 如 的 监视 旧 个 同 的 是 ， 线 程 池 的 监视 右 没 有 泣 赤 过 去 儿 分 钟 线 程 池 
活动 的 折线 图 。 


右上 和 角 显示 线程 池 有 的 名 称 ， 其 下 方 是 线程 池 中 的 线程 每 秒 钟 处 理 请 
求 的 数量 。 线 程 池 监视 项 的 左下 角 显 示 如 下 信息 。 


。 活跃 线程 : 当前 活跃 线程 的 数量 。 

。 排队 线程 .当前 有 多 少 线程 在 排队 。 上 默认 情况 下 ， 队 列 功能 是 茶 用 
的 ， 所 以 这 个 值 始 终 为 0。 

。 线程 池 的 大 小 : 线程 池 中 有 多 少 线程 。 


在 右 下 角 显 示 线 程 池 的 其 他 信息 : 


。 最 大 活路 线程 在 当前 的 采样 周期 中 ， 活 路 线程 的 最 大 数量 。 

。 执行 次 数 ， 线程 池 中 的 线程 被 调用 执行 Hystrix 命 令 的 次 数 。 

。 线程 队列 大 小 : 线程 池 队 列 的 大 小 。 线 程 队列 功能 默认 是 共用 的 ， 
所 以 这 个 值 没有 什么 音义 。 


值得 一 提 的 是 ， 作 为 Hystrix 线 程 池 的 蔡 代 方案 ， 我 们 可 以 选择 使 用 
信号 量 隔 离 (semaphore isolation ) 。 然 和 而， 信号 量 隔离 是 Hystrix 的 更 高 
级 用 法 ， 超 出 了 本 和 章 的 和 范围。 有关 它 的 更 多 信息 ， 请 参考 Hystrix 的 文 
档 。 


现在 ， 我 们 已 经 看 到 了 Hystrix dashboard 是 如 何 运行 的 。 接 下 来 ， 
我 们 考虑 一 下 如 何 处 理 多 个 断路 絮 数 据 流 ， 以 及 如 何 将 它们 聚合 到 一 个 
流 中 ， 以 便 在 Hystrix dashboard 中 查看 。 


15.4 ” 腿 合 多 个 Hystrix 尝 


Hystrix dashboard 一 次 只 能 监控 一 个 法。 因为 每 个 微服 务实 例 都 友 
布 它 们 目 己 的 Hystrix， 所 以 几乎 不 可 能 对 整个 应 用 的 健康 状况 历史 有 一 
个 整体 的 了 解 。 


驻 运 的 是 ，Netflix 的 男 一 个 项 目 Turbine 提 供 了 将 所 有 人 微服 务 的 所 有 
Hystrix 流 聚合 到 一 个 Hystrix 流 中 的 办 法 ， 这 样 Hystrix dashboard 就 能 对 
其 进行 监控 了 。Spring Cloud Netflix 文 持 以 类 似 于 创建 其 他 Spring Cloud 
服务 的 方式 创建 Turbine 服 务 。 要 创建 Turbine 服 务 ， 我 们 需要 创建 一 个 
新 的 Spring Boot 项 目 并 将 Turbine starter 依 赖 洪 加 a 到 构建 文件 中 : 


<dependency> 
<grouplId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-netflix-turbine</artifactId> 
</dependency> 








注意 :; 作为 一 个 新 项 目 ， 最 简单 的 方式 是 在 创建 新 Spring 


Boot 项 目的 时 候 在 Initializr 中 选中 Turbine 复 选 框 。 





在 创建 完 新 项 目 之 后 ， 我 们 需要 局 用 Turbine。 为 了 实现 这 一 点 ， 我 
们 需要 在 应 用 的 主 配 置 类 上 添加 @EnableTurbine 注 解 : 
@SpringBootApplication 


@EnableTurbine 
public class TurbineServerApplication { 


public static void main(String[] args) { 
SpringApplication.run(TurbineServerApplication.class, args); 





在 开发 阶段 ， 我 们 会 和 Taco Cloud 应 用 的 其 他 服务 一 起 在 本 地 运行 
Turbine。 为 了 避免 问 口 冲突 ， 我 们 需要 为 Turbine 选 择 一 个 唯一 的 闹 
中 ， 这 样 就 不 会 与 其 他 的 服务 产生 冲突 了。 你 可 以 选择 任意 的 病 口 ， 不 
过 我 倾 癌 于 选择 8989: 


Turbine 会 消费 多 个 人 微服 务 的 流 并 将 它们 的 断路 颖 指标 合并 到 一 个 沈 
中 。 它 会 作为 Eureka 的 客户 端 ， 发 现 那 些 需 要 聚合 到 上 自己 的 流 的 服务 。 
但 是 ，Turbine 并 不 想 有 聚合 Eureka 中 注册 的 所 有 流 ， 所 以 我 们 必须 配置 
Turbine， 告 诉 它 都 要 使 用 哪些 服务 。 


turbine.app-config 属 性 会 接受 一 个 由 至 写 分 隅 的 服务 名 称 列 表 ， 


Turbine 会 在 Eureka 中 查找 它们 并 聚合 它们 的 Hystrix 流 。 对 Taco CloudY 
用 来 讲 ， 我 们 需要 注册 在 Eureka 中 的 4 个 服务 ， 即 ingredient-service、 
taco-servVice、order-service 和 user-service。 如 下 的 application.yml 配 置 条 目 


展现 了 如 何 放 置 turbine.app-config: 


turbine: 


app-config: ingredient-service,taco-service,order-service,user-service 
cluster-name-expression: "'default'" 





注意 ， 除 了 turbine.app-config 之 外 ， 我 们 还 将 turbine.cluster-name- 
expression 属 性 设置 成 了 “default”。 这 表明 Turbine 会 收集 名 为 default 的 
集群 中 的 所 有 聚合 法 。 设 置 这 个 属性 是 非常 重要 的 ， 人 奋 则 Turbine 中 不 会 
包含 任何 特定 应 用 的 聚合 流 数 据 。 


现在 ， 司 动 Turbine 服 务 器 并 让 Hystrix dashboard 访 问 
http://localhost:8989/ turbine.stream 地 址 上 的 沪 ， 特 定 应 用 的 所 有 上 断路 大 
都 将 会 展现 在 断路 器 dashboard 上 ， 如 图 15.6 所 示 。 


Oe : 国 全 Ly localhost 








一 
Hystrix Stream: http://localhost:8989/turbine.stream (5 HYSTRIX 
DEFEND YOUR APP 
Circuit Sor: Error then Volume | Alphabetical | Volume | Error | Mean | Median | 90199199.5 Suceess | Short-Circuited | Bad Regquest | Timeout | Rejected | Failure | Error % 
recentTacos allOrders alllngredients userByUserld 
~ 25|0|35 9% 40|0 14 | 0 13 | 0 
0|0 0|0 0 0 0|0 
1 0 0 0 
0.7/s 0.4/s 1.3/s 1.3/s 
1.3/s 1.3/s 1.3/s 1.3/s 
( Ci sed Circuit 
2 Soth 1m 10848 3 昌 1ms Hosts 1 90t 1ms HOSts 1 Soth i1ms 
an Oms Seth 6ms Median Oms 99th 1ms Medan 1ms 99th tms Median Oms 99th 1ms 
Mean Oms 99.5th 6ms Mean Oms 99.5th 1ms Mean Oms 99.5th tms Mean Oms 人 多. 印 1ms 
Thread Pools Sort: Alphabetical | Volume | 
IngredientsController UsersController TacosController OrdersController 
1.4/s 1.3/s 0.7/s 0.4/s 
1.4/s 1.3/s 1.3/s 1.3/s 
Aciive 0 “ax Active 1 Actwe 0 Max Active 1 Active 0 Max Active 2 Actve 0 Max Active 3 
Queued 0 Execulions 14 Queuwed 0 ExecUtions 13 QUeUued 0 Executions 26 [JUBUd 0 Exweculions 39 
Pool Size 10 Queue Sze 5 Pood Size 10 Queue Size 5 Pool Size 20 Dueue Size 5 Pool Sze 30 Queue Size 5 


图 15.6” 当 访问 聚合 的 Turbine 流 时 Hystrix dashboard 会 显示 所 有 服务 的 所 有 上 断路 器 


Hystrix dashboard 能 够 展现 所 有 服务 的 所 有 上 断路 器 要 归功 于 


Turbine。 这 样 ， 我 们 整 能 够 一 站 式 地 监控 Taco Cloud 应 用 所 有 上 岂 路 堪 的 
健康 状况 了 。 


15.5 ”小结 


源 路 妖 模 式 能 够 优雅 地 进行 失败 处 理 。 

Hystrix 实 现 了 断路 器 模式 ， 能 够 在 茶 个 方法 失败 或 执行 太 悍 的 时 候 
司 用 后 备 行 为 。 

Hystrix 提 供 的 每 个 断路 器 都 会 以 数据 流 的 方式 发 布 指 标 信 息 ， 以 便 
于 监控 应 用 的 健康 状况 。 

Hystrix 吕 以 被 Hystrix Dashboard 消 费 ， 这 十 一 个 可 视 化 断路 磺 指 标 
有 Web 应用。 

Turbine 能 够 将 多 个 应 用 的 Hystrix 流 聚合 到 一 个 流 中 ， 以 便 在 Hystrix 
Dashboard 中 统一 进行 可 视 化 展现 。 





[1] 


不 知道 你 是 不 是 像 我 一 样 ， 觉 得 以 注解 的 形式 为 其 他 注解 设置 属性 


的 方法 有 所 诡异 。 不 官 十 不 是 觉得 人 诡异， 这 束 古 目前 的 做 法 。 


在 第 5 部 分 中 ， 我 们 将 会 介绍 如 何 为 应 用 的 部 普 做 好 准备 ， 并 且 会 
尝 习 如 何 进行 部 署 。 第 16 章 介绍 Spring Boot Actuator。 这 是 Spring Boot 
的 一 个 扩展 ， 以 REST 端 点 和 JMX MBean 的 形式 暴露 正在 运行 中 的 应 用 
的 内 部 状况 。 在 第 17 草 中， 我 们 将 会 看 到 如 何 使 用 Spring Boot Admin。 
它 基 于 Actuator 提 供 了 一 个 用 户 友 好 的 、 基 于 浏览 器 的 官 理 型 应 用 。 我 
们 将 会 看 到 如 何 注 册 客 户 问 应 用 以 及 如 何 保护 Admin Server。 第 18 草 将 
讨论 如 何以 JMX MBean 的 形式 骏 圳 和 消 弓 Spring bean。 在 最 后 的 第 19 草 
中 ， 我 们 将 会 看 到 如 何 将 Spring 应 用 部 童 到 各 种 生产 环境 中 。 部 闭 过 基 
于 Java 悄 用 的 人 可 能 认为 这 轻而易举 ， 但 是 Spring Boot 和 相关 的 Spring 
项 目 有 很 多 特性 ， 使 得 Spring Boot 应 用 的 部 著 有 些 不 同 。 


第 16 章 ”使 用 Spring Boot Actuator 


。 在 Spring Boot 项 目 中 局 用 Actuator 


。 探索 Actuator 的 端点 
e。 目 定 义 Actuator 


e 保护 Actuator 





你 有 没有 试图 猜 调 包 疤 好 的 礼物 盒 中 到 撒 有 什么 东西 的 经 历 ” 你 可 
能 摇晃 、 搞 量 或 者 用 尺子 测量 它 。 对 于 里 面 有 什么 东西 ， 你 可 能 会 有 一 
个 确定 的 想法 。 但 是 ， 在 真正 将 它 打开 之 前 ， 我 们 无 法 完全 确定 。 


运行 中 的 应 用 有 后 像 包 波 好 的 礼物 。 你 可 以 探 误 一 下 它 ， 然 后 对 里 
面 的 运行 状况 做 出 一 个 合理 的 猜测 。 但 是 ， 我 们 该 如 何 确 定 呢 ? 如 采 能 
有 一 种 方式 让 我 们 颖 探 运 行 中 的 应 用 ， 假 设 我 们 能 够 得 看 它 的 行为 、 检 
便 它 有 的 健康 状况 ， 甚 至 触 友 影 啊 它 运行 的 各 种 操作 ， 那 束 太 好 J 了! 


在 本 章 中 ， 我 们 将 会 讨论 Spring Boot 的 Actuator。Actuator 提 供 了 生 
产 环 境 可 用 的 特性 ， 包 括 监控 Spring Boot 应 用 和 获取 它 的 各 种 指标 。 
Actuator 的 特性 是 通过 各 种 端点 提供 的 ， 这 些 端点 可 以 通过 HTTP 调 用 ， 
也 可 以 通过 JMX MBean 来 使 用 。 在 本 半 中 ， 我 们 主要 关注 HTTP 闻 所 ， 
而 对 JMX 珊 后 的 介绍 留 到 第 19 半 。 


16.1 Actuator 概 览 


在 机 器 领域 中 ， 执 行 机 构 (Actuator〉 指 的 是 负责 控制 和 移动 装置 
的 组 件 。 在 Spring Boot 应 用 中 ，Spring Boot Actuator 扮 演 了 相同 的 角 
色 ， 它 能 够 让 我 们 看 到 一 个 运行 中 的 应 用 的 内 部 状况 ， 而 且 能 够 在 一 定 
程度 上 控制 应 用 的 行为 。 


通过 Actuator 暴 露 的 病 点 ， 我 们 可 以 获取 一 个 正在 运行 中 的 应 用 的 
内 部 状态 。 


。 在 应 用 环境 中 ， 都 有 哪些 可 用 的 配置 属性 ? 

e。 在 应 用 中 ， 各 个 源码 包 的 日 志 级 别 是 什么 ? 

。 应 用 消耗 了 多 少 内 存 ? 

。 给 定 的 HTTP 闹 点 裤 请 求 了 多 少 炊 ? 

。 应 用 本 和 刁 以 及 与 它 协作 的 外 部 服务 的 健康 状况 如 何 ? 


为 了 在 Spring Boot 应 用 中 启用 Actuator， 我 们 需要 在 构建 文件 中 添 
加 对 Actuator starter 的 依赖 。 在 Spring Boot 心 用 的 Maven pom.xml 文 件 
中 ， 添 加 如 下 的 <dependency> 条 目 就 能 完成 该 任务 : 


sdependency， 


<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-actuator</artifactId> 
</dependency> 


将 Actuator starter 深 加 到 项 目的 构建 文件 中 之 后 ， 应 用 开会 具备 一 
些 开 箱 即 用 的 Actuator 问 点 ， 其 中 一 部 分 如 表 16.1 所 示 。 





表 16.1 探查 运行 中 Spring Boot 尿 用 的 状态 并 对 其 进行 操作 的 Actuator 闹 点 









GET 生成 所 有 已 触发 的 审计 事件 的 报告 


a 生成 一 个 目 动 配置 条 件 通 过 或 失败 的 报告 ， 
conditions 

这 些 条 件 会 指导 应 用 上 下 文中 bean 的 创建 
摘 述 所 有 的 配置 属性 以 及 当前 的 值 


生成 Spring 应 用 可 用 的 所 有 属性 源 以 及 可 用 
属性 的 报告 


/env/{toMatch} | 描述 某 个 环 声 属性 的 值 








返回 聚合 的 应 用 健康 状态 ， 可 能 的 话 ， 还 会 
GET /health 包含 外 部 依赖 应 用 的 健康 状态 


Pi 


/heapdump 下 载 堆 dump 文 件 


ee 生成 最 近 100 个 请 求 的 跟踪 结果 
友人 员 定义 的 关于 该 有 的 人 


生成 应 用 中 源码 包 的 列表 ， 其 中 会 包含 配置 
GET /loggers 、 合 
的 以 及 生效 的 日 志 级 别 
返回 指定 logger 配 置 的 和 生效 的 日 志 级 别 ， 
GET、 POST |/loggers/{name} ek CR 省 
生效 的 日 志 级 别 可 以 通过 POST 请 求 修 改 












返回 所 有 指标 分 类 的 列表 


/metrics/{name} | 返回 给 定 指 标的 多 维度 值 集 





/Scheduledtasks | 列 出 所 有 的 调度 任务 


生成 所 有 HTTP 了 映射 及 其 对 应 处 理 占 方法 的 
/mappings 报 生 


下 /threaddump 返回 所 有 应 用 线程 的 报告 


除了 基于 HTTP 的 端点 之 外 ， 表 16.1 中 除 “heapdump” 的 其 他 端点 都 


以 JMX MBean 的 形式 对 外 雄 露 了 出 来 。 我 们 将 会 在 第 19 半 学 习 JMX 侧 的 


Actuator。 


16.1.1 配置 Actuator 的 基础 路 径 


默认 情况 下 ， 表 16.1 中 所 有 端点 的 路 径 都 会 带 有 ”actuator”。 这 意味 
着 ， 如 果 我 们 想 要 通过 Actuator 获 取 应 用 的 健康 信息 ， 那 么 
问 “/actuator/health” 发 送 GET 请 求 束 能 返回 所 需 的 信息 。 


Actuator 的 前 组 可 以 通过 设置 management.endpoint.web.base-path 必 
性 来 修改 。 例 如 ， 想 要 将 前 绥 设 置 为 “management”， 那 么 我 们 可 以 通 
过 如 下 的 方式 来 设置 management. endpoint.web.base-path 属 性 : 


management : 
endpoints: 


Web : 
base-path: /management 





按照 上 述 属性 ， 要 获取 应 用 的 健康 信息 ， 我 们 需要 
问 “/management/health” 发 送 GET 请 求 。 


16.1.2 ”局 用 和 禁用 Actuator 闹 所 


你 可 能 已 经 友 现 ， 默 认 情 况 下 ， 只 有 “/health” 和 /info” 并 点 是 局 用 
的 。 大 多 数 Actuator 闪 点 会 携 市 敏感 信息 ， 所 以 应 该 体 护 起 来 。 我 们 可 
以 使 用 Spring Security 来 锁定 Actuator， 但 是 因为 Actuator 本 号 没有 安全 
保护， 所 以 大 多 数 新 点 献 认 部 是 禁用 的 ， 需 要 我 们 来 选择 对 外 雄 露 哪些 


dy、 


有 两 个 配置 属性 能 够 控制 对 外 又 嚣 哪些 细 点 ， 它 们 分 别 古 
management.endpoints.web.exposure.include 和 和 
management.endpoints.web.exposure.exclude。 通 过 
management.endpoints.web. exposure.include 属 性 ， 我 们 可 以 指定 哪些 站 
点 想 要 暴露 出 来 。 例 如 ， 想 要 暴 
露 “health”“%info”“%beans” 和 “conditions” 的 话 ， 我 们 可 以 通过 如 下 的 配置 
来 声明 : 


management : 
endpoints: 


Web : 
exposure: 
include: health,info,beans,conditions 





management.endpoints.web.exposure.include 属 性 也 可 以 接受 星 号 
(*) 作为 通配符 ， 表 明 所 有 的 Actuator 站 点 都 会 对 外 其 露 : 


management : 
endpoints: 


web: 


exposure: 
include: ‘'*" 





点 之 外 ， 我 们 想 骏 露 其 他 的 所 有 痪 点， 那么 一 般 来 
讲 更 简单 的 方式 是 通过 通配符 将 它们 全 部 包含 进 有 来， 然后 明确 排除 一 部 
分 。 人 例如， 我们 想 要 暴露 除了 “threaddump” 和 “heapdump” 之 外 的 端 

点 ， 那 么 可 以 按照 如 下 的 形 陈 同时 放置 


management.endpoints.web.exposure.include 和 


如 果 除 了 个 列 关 


management.endpoints.web.exposure.exclude 属 性 : 


management: 
endpoints: 
Web : 


exposure: 
include: ‘*' 
exclude: threaddump,heapdump 





如 果 你 决定 对 外 公开 比 “/health”* 和 “/info” 更 多 的 信息 ， 那 么 最 好 配 
置 Spring Security 来 限制 对 其 他 病 点 的 访问 。 我 们 将 会 在 16.4 节 中 了 解 如 
何 保护 Actuator 哨 点。 现在， 我 们 看 一 下 如 何 消 费 Actuator 对 外 和 骏 露 的 
HTTP 闪 点 。 


16.2 ”消费 Actuator 闪 点 


Actuator 是 一 个 真正 的 宝 减 ， 我 们 可 以 通过 表 16.1 列 出 的 HTTP 闹 点 
攻取 正在 运行 中 的 应 用 的 有 用 信息 。 作 为 HTTP 端 点 ， 它 们 可 以 像 任意 
REST API 那 样 被 消费 ， 我 们 可 以 选择 任 童 的 HTTP 客 户 闹 ， 包 括 Spring 
的 RestTemplate 和 WebClient、 基 于 浏览 右 的 JavaScript 必 用 以 及 人 简单 的 


cunl 命 令 行 客户 病 。 


在 探 过 Actuator 绒 点 的 过 程 中 ， 我 们 将 会 在 本 章 中 使 用 curl 命 令 行 铝 
尸 疾 。 在 第 17 半 中 ， 我 将 会 为 你 介绍 Spring Boot Admin， 这 是 一 个 构建 
在 Actuator 喘 点 之 上 的 用 户 友 好 的 Web 应 用 。 


为 了 了 了解 Actuator 都 提供 了 哪些 病 点 ， 我 们 可 以 同 Actuator 的 基础 路 
低 发 送 一 个 GET 请 求 ， 这 样 能 够 得 到 每 个 新 点 的 HATEOAS 和 链接 。 如 果 


使 用 curl 向 “/actuator” 发 送 一 个 请 求 ， 那 么 我 们 将 会 看 到 如 下 所 示 的 响应 
(为 了 节省 空间 ， 进 行 了 删 减 ) : 


$ curl 1ocalhost:8681/actuator 
{ 
" links": { 
"self": { 
"href": "http://localhost:806081/actuator", 
"templated": false 
}, 
"auditevents": { 
"href": "http://localhost:80681/actuator/auditevents",， 
"templated": false 


"href": "http://localhost:806081/actuator/beans",， 
"templated": false 


"href": "http://localhost:806081/actuator/health",， 
"templated": false 





因为 不 同 的 库 可 能 会 页 献 目 己 的 Actuator 员 点 而 且 荣 些 细 点 可 能 汽 
有 对 外 雄 露 ， 所 以 不 同 应 用 之 间 的 实际 结果 也 许 会 有 所 差异 。 


不 管 在 什么 情况 下 ，Actuator 基 础 路 径 提 供 的 链接 集合 都 可 以 作为 
Actuator 所 提供 端点 的 一 幅 地 图 。 我 们 首先 从 两 个 提供 应 用 基本 信息 的 
六 点 开始 探索 Actuator， 这 两 个 端点 束 是 “/health” 和 “</info”。 


16.2.1 获取 应 用 的 基础 信息 


在 去 医院 看 病 的 时 候 ， 医 生 通 沼 会 站 和 完 问 两 个 问题 ， 你 是 谁 ?你 感 


觉 怎 样 ? 尺 官 医生 或 护士 选择 的 说 法 可 能 会 有 所 不 同 ， 但 是 他 们 的 最 终 
目的 部 是 想 要 了 解 接 诊 的 人 以 及 为 什么 要 去 医院 找 医生 看 病 。 


Actuator 的 %info” 和 “health” 闪 点 为 Spring Boot 应 用 同等 重要 的 问题 
提供 了 答案 。%info" 站 点 告诉 我 们 关于 应 用 的 信息 ， 而 “health” 靖 点 则 
告诉 我 们 应 用 健康 状况 的 信息 。 


请 求 天 于 应 用 的 信息 


要 了 解 正在 运行 中 的 应 用 的 信息 ， 我 们 可 以 请 求 Yinfo”* 兽 后 。 但 
征 ， 黑 认 人 情况 下 ，%info” 并 不 会 提供 什 么 信息 。 如 下 是 我 们 便 用 cun 肥 
送 请 求 后 可 能 会 看 到 的 效 末 : 


$ curl 1Localhost :8681/actuator/info 
{} 


虽然 这 样 看 起 来 ，”%info” 问 点 似乎 没有 太 大 的 用 处 ， 但 是 我 们 最 好 
将 它 视 为 一 块 干 净 的 画布 ， 我 们 可 以 在 上 面 绘制 任何 想 要 展现 的 信息 。 


我 们 可 以 有 多 种 为 “/info” 新 点 提供 信息 的 方式 ， 但 是 最 人 简单 直接 的 
就 是 创建 一 个 或 多 个 属性 名 带 有 “info.” 前 绥 的 配置 属性 。 人 例如， 假设 我 
们 和 希望 在 %info" 的 啊 应 中 包含 售后 文 持 的 联系 信息 ， 包 括 Email 地 址 和 电 
话 号 但。 为 了 实现 这 一 点 ， 我 们 可 以 在 application.yml 文 件 中 配置 如 下 
的 属性 : 


1Info : 
contact: 


email: support@tacocloud.conm 
phone: 822-625-6831 





对 于 Spring Boot 和 和 应 用 上 下 文中 的 bean 来 襄 ，info.contact.ematil 
property 和 info.contact.phone 属 性 可 能 都 没有 什么 特殊 的 意义 。 但 是 ， 
为 它们 的 前 弘 是 info， 所 以 %/info” 逆 点 将 会 在 啊 应 中 包含 这 两 个 属性 的 
值 : 

{ 


"contact": { 
“email": "support@tacocloud.com", 
phone : "822-625-6831" 

} 





} 


在 16.3.1 小 下， 我 们 将 会 看 到 使 用 关于 应 用 的 有 用 信息 来 需 
充 %info” 疹 点 的 其 他 几 种 方式 。 


探查 应 用 的 健康 状况 


发 送 HTTP GET 请 求 到 “health” 端 点 将 会 得 到 一 个 简单 的 JSON 响 
应 ， 其 中 包含 了 应 用 的 健康 状态 。 例 如 ， 如 下 是 我 们 使 用 curl 访 
问 “/health” 闹 点 可 能 看 到 的 啊 应 : 


$ curl localhost:8060806/actuator/health 





{"status":"UP"} 


你 可 能 会 想 ， 一 个 咽 扣 报告 应 用 的 状态 是 UP， 这 能 有 什么 用 处 
了 呢 。 如 末 应 用 停 反 ， 那 么 它 义 该 报 生 什么 呢 ? 


实际 上 ， 这 里 显示 的 是 一 个 或 多 个 健康 指示 需 的 聚合 状态 。 健 康 指 
示 器 会 报告 应 用 要 与 之 交互 的 外 部 系统 的 健康 状态 ， 比 如 数据 库 、 消 息 
代理 甚至 Spring Cloud 组 件 ， 比 如 Eureka 和 Config Server。 每 个 指示 器 的 


健康 状态 可 能 会 是 如 下 的 可 选 信 中 的 未 一 个 。 


e。 UP: 外 部 系统 已 经 启动 并 且 可 以 访问 。 

。DOWN: 外 部 系统 已 经 停机 或 者 不 可 访问 。 

。 UNKNOWN: 外 部 系统 的 状态 尚 不 清楚 。 
。OUT_OF_SERVICE: 外 部 系统 可 以 访问 得 到 ， 但 是 目前 不 可 用 。 


所 有 健康 指示 从 的 状态 会 聚合 成 应 用 整体 的 健康 状态， 这 个 过 程 中 
会 使 用 如 下 的 规则 。 


。 如 果 所 有 指示 器 都 是 UP， 那 么 应 用 的 健康 状态 是 UP。 

。 如 果 一 个 或 多 个 健康 指示 器 是 DOWN， 那 么 应 用 的 健康 状态 就 是 
DOWN。 

。 如 果 一 个 或 多 个 健康 指示 器 是 OUT_OF_ SERVICE， 那 么 应 用 的 健 
康 状 态 就 是 OUT_OF_SERVICE。 

。 UNKNOWN 的 健康 状态 会 被 忽略 ， 不 会 计 入 应 用 的 聚合 状态 中 。 


套 认 情况 下 ， 请 求 </health” 端 后 的 啊 应 中 只 会 包含 聚合 的 状态 。 但 
是 ， 我 们 可 以 配置 management.endpoint.health.show-details 属 性 ， 以 便于 
展示 有 所 有 健康 指示 妖 的 完整 细 方 : 


management: 
endpoint: 


health: 
show-details: always 





management.endpoint.health.show-details 属 性 的 默认 值 是 never。 我 们 
可 以 将 它 设 置 成 always， 这 样 束 会 始终 显示 健康 指示 融 的 完整 细 节 ; 也 
可 以 将 其 设置 成 when-authorized， 只 有 妆 客 己 病 是 完整 认证 的 情况 下 才 


展示 完整 的 细 市 信息 。 


现在 ， 我 们 向 “health” 端 点 发 送 GET 请 求 的 话 ， 就 会 得 到 健康 指示 
器 的 完整 细节 。 如 下 是 一 个 与 Mongo 文 档 数 据 库 集成 的 服务 样 例 ; 


{ 
Status : “UP ， 


"details": { 
"mongo": { 
“Status : “UP ， 
"details": { 
“Verslon : "3.2.2" 
} 
}, 


"diskSpace": { 
“Status : "UP", 
"details": 
"total": 499963170816 ， 
"free": 177284784128 ， 
"threshold": 16485760 





所 有 的 应 用 ， 不 管 其 外 部 依赖 是 什么 ， 至 少 都 会 有 一 个 针对 文件 系 
统 的 健康 指示 器 ， 名 为 diskSpace。diskSpace 健 康 指 示 器 能 够 显示 文件 系 
统 的 健康 状况 〈 和 布 望 它 是 UP 状态 ) ， 这 个 状态 的 值 是 由 还 有 多 少 剩余 
宝 间 雇 定 的 。 如 末 可 用 修 盘 空间 低 于 国 什 ， 那 么 它 将 会 报告 DOWN 的 状 
太 


JUN o 


在 前 面 的 样 例 中 ， 还 有 一 个 mongo 健 康 指示 亏 ， 它 报告 了 Mongo 数 
据 库 的 状态 。 细 节 信 息 包 括 了 Mongo 数 据 库 的 版 本 。 


目 动 配置 功能 能 够 确保 只 有 与 应 用 程序 相关 的 健康 指示 旨 才 会 时 不 
到“/health” 端 点 中 。 除 了 mongo 和 diskSpace 健 康 指示 器 ，Spring Boot 还 


为 多 个 外 部 数据 库 和 系统 提供 了 健康 指示 益 ， 包 括 : 


Cassandra 
Config Server 
Couchbase 
Eureka 
Hystrix 
JDBC 数 据 源 
Elasticsearch 
InfluxDB 

JMS 消 明代 理 
LDAP 
Email 服 务 妖 
Neo4] 
Rabbit 消 明代 理 
Redis 

Solr 


万 外 ， 第 三 方 库 可 以 贡献 目 己 的 健康 指示 硕 。 我 们 将 会 在 16.3.2 小 


世 看 一 下 如 何 编 与 目 定 义 的 健康 指示 耸 。 


我 们 可 以 看 到 “Vinfo” 和 “/health”* 病 点 提供 了 正在 运行 中 的 应 用 的 基 


本 信息 。 同 时 ， 还 有 一 些 其 他 的 Actuator 端 点 能 够 探查 应 用 内 部 的 配置 
信息 。 接 下 来 ， 我 们 看 一 下 Actuator 是 如 何 展 现 应 用 的 配置 的 。 


16.2.2 ”和 否 看 配置 细 古 


除了 接收 应 用 的 基本 信息 之 外 ， 了 解 应 用 是 如 何 配置 的 也 很 有 指导 
意义 。 例 如 ， 应 用 上 下 文中 都 有 哪些 bean? 目 动 配置 中 哪些 条 件 通过 
了 ， 哪 些 条 件 失 败 了 ? 应 用 中 有 了 哪些 可 用 的 环境 变量 ? HTTP 请 求 是 如 
何 映射 控制 豆 的 ? 未 些 包 或 类 所 设置 的 日 忘 级 别 是 什么 ? 


这 些 问 题 可 以 通过 Actuator 
的 “beans”“%conditions”“yenv2”“yconfigprops”“ymappings” 和 “loggers” 病 操 
来 回答 。 在 有 些 情 况 下 ， 我 们 甚至 还 可 以 使 用 ”yenv” 和 “loggers” 问 点 ， 
在 应 用 运行 的 过 程 中 对 配置 信息 进行 调整 。 我 们 将 会 逐个 看 一 下 这 些 病 
护 ， 它 们 能 够 让 我 们 洞察 正在 运行 中 的 应 用 的 配置 情况 。 下 面 和 有 先 
从 “beans” 闪 点 开始 。 


获取 bean 的 浅 配 报告 


要 研究 Spring 应 用 上 和 下文， 最 基础 的 端点 就 是 “beans”。 这 个 端点 返 
回 的 JSON 文 档 描述 了 应 用 上 下 文中 的 每 个 bean， 其 中 包括 它 的 Java 类 型 
以 及 它 被 注入 的 其 他 bean。 


对 “/beans” 闹 点 发 送 GET 请 求 的 完整 啊 应 可 以 轻松 地 填 满 这 一 整 
章 。 所 以 ， 我 们 不 会 列 出 “/beans” 的 完整 啊 应 ， 而 是 只 考虑 下 面 的 片 
段 ， 主 要 关注 一 个 bean 条 日 : 





{ 


"contexts": { 
"application-1": { 
"beans": { 


"ingredientsController": 1{ 
"aliases": [|]， 


"scope": "singleton", 

"type": "tacos.ingredients.IngredientsController",， 

"resource": "file [/Users/habuma/Documents/Workspaces/ 
TacoCloud/ingredient-service/target/classes/tacos/ 
ingredients/IngredientsController.class|",， 

"dependencies": | 
"ingredientRepository" 

] 

}, 


}, 
“parentId : null 





吧 应 的 根 元 际 是 contexts， 它 包含 了 一 个 子 元 素 ， 代 表 应 用 中 的 每 
个 Spring 应 用 上 下 文 。 在 每 个 应 用 上 下 文中 ， 都 有 一 个 beans 元 素 ， 它 包 
舍 了 应 用 上 下 文 所 有 bean 的 细 贡 。 


在 上 面 的 样 例 中 ， 显 示 了 名 为 ingredientsController 的 bean。 我 们 可 
以 看 到 ， 它 没有 别名 ，scope 是 singleton 并 日 类 型 为 
tacos.ingredients.IngredientsController。 男 外 ，resource 属 性 指 癌 了 定义 这 
个 bean 的 类 文件 路 径 。dependencies 属 性 列 出 了 注入 到 给 定 bean 的 所 有 其 
他 bean。 在 本 例 中 ，ingredientsController 被 注入 了 一 个 名 为 


ingredientRepository 的 bean。 
前 述 目 劲 闻 配 


我 们 可 以 看 到 ， 自 动 装 配 是 Spring Boot 提 供 的 最 强大 的 功能 之 一 。 
但 是 ， 有 时候 你 可 能 想 要 知道 这 些 功 能 为 什么 会 目 动 装 配 在 一 起 。 或 
者 ， 你 认为 菜 些 功能 已 经 目 动 装配 了 ， 但 是 它们 实际 上 却 没 有 ， 你 可 能 


想 要 知道 原因 所 在 。 在 这 种 情况 下 ， 我 们 可 以 同 “Vconditions” 发 送 GET 
请 求 ， 这 样 我们 会 知道 目 动 装配 过 程 中 都 发 生 了 什么 


“/conditions” 病 点 的 目 动 六 配 报 告 可 以 分 为 3 部 分 : 匹配 上 的 
(positive matches， 即 已 通过 的 条 件 化 配置 ) 、 未 匹配 上 的 (negative 
matches， 即 失败 的 条 件 化 配置 ) 以 及 非 条 件 化 的 类 。 如 下 的 厂 段 是 
对 “/conditions” 请 求 的 啊 应 ， 展 现 了 每 个 组 成 部 分 的 示例 : 


"contexts": { 
"application-1": { 
"positiveMatches": 1{ 


"MongoDataAutoConfiguration#mongoTemplate": | 
{ 
"condition": "OnBeanCondition",， 
"message": "QConditionalOnMissingBean (types : 
org.springframework.data.mongodb.core.MongoTemplate; 
SearchStrategy: all) did not find any beans" 


} 
]， 


}， 


"negativeMatches": { 


"DispatcherServletAutoConfiguration": { 
"notMatched": | 


{ 
"condition": "OnClassCondition",， 
"message": “QConditionalOnClass did not find required 
class ‘org.springframework .web.servlet. 
DispatcherServlet'" 
} 
]， 
"matched": | 
}, 
}, 


"unconditionalClasses": | 


"org.springframework.boot.autoconfigure.context. 


ConfigurationPpropertiesAutoConfiguration',， 





PO 中 ， 我 们 可 以 看 到 通过 目 动 配置 创建 了 一 个 
MongoTemplate bean， 这 和 古 因 为 目前 上 下 文中 还 没有 这 样 的 bean。 导 致 
这 种 配置 结果 的 原因 是 这 里 包含 了 @ConditionalOnMissingBean 注 解 ， 如 
果 没 有 明确 配置 这 个 bean， 束 会 日 动 配置 它 。 在 本 例 中 ， 并 没有 找到 
MongoTemplate 类 型 的 bean， 因 此 上 自动 配置 功能 介入 并 创建 了 一 个 该 类 
型 的 bean。 


在 negativeMatches 区 域 中 ，Spring Boot 要 尝试 配置 一 个 
DispatcherServlet。 但 是 ，@ConditionalOnClass 条 件 化 注解 失败 了 ， 这 是 
为 没有 找到 DispatcherServlet 类 。 


最 后 ， 在 unconditionalClasses 区 域 中 是 一 个 无 条 件 配置 的 
ConfigurationPropertiesAutoConfiguration。 配 置 属性 是 Spring Boot 操 作 的 
基础 ， 所 以 任何 与 配置 属性 相关 的 配置 都 应 该 无 条 件 上 自动 痛 配 


探查 环境 和 配置 属性 


除了 知道 应 用 的 bean 是 如 何 装 配 在 一 起 的 ， 我 们 可 能 还 对 有 哪些 可 
用 的 环境 属性 以 及 bean 中 都 注入 了 哪些 配置 属性 感 兴 


当 我 们 问 %Venv” 病 后 友 太 GET 请 求 的 时 候 ， 我 们 会 得 到 一 个 非 第 长 
的 啊 应 ， 它 包含 了 Spring 应 用 中 所 有 友 挥 作用 的 属性 源 。 其 中 包括 来 目 


环境 变量 、JVM 系 统 属性 、application.properties 和 application.yml 文 件 其 
至 来 目 Spring Cloud Config Server 〈 访 应 用 是 Config Server 客 户 新 ) 的 属 
性 。 


程序 清单 16.1 列 出 了 “%env” 闪 点 能 够 得 到 的 啊 应 示例 ， 不 过 进行 了 
删 减 ， 这 样 你 会 对 它 所 提供 的 信息 有 一 个 大 致 了 解 : 
程序 清单 16.1 “env” 端 点 的 结果 


$ curl localhost:80681/actuator/env 


{ 
"activeProfiles": | 
"development" 
] ， 
"propertySources": | 
{ 
name : "systemEnvironment",， 
"properties": { 
"PATH": { 
"value": "/usr/bin:/bin:/usr/sbin:/sbin",， 
"origin": System Environment Property \ PATHA 
}, 
"HOME": { 
"value": "/Users/habuma",， 
"origin": System Environment Property \ HOMEN\ 
} 
} 
}, 


"name": "applicationConfig: [classpath:/application.yml|",， 
"properties": { 
"spring.application.name": { 
"value": "ingredient-service", 
"origin": “class path resource [application.yml|:3:11" 
}, 
"server.port": 1{ 
"value": 8081， 
"origin": "class path resource [application.yml|:9:9" 


}， 





%env" 的 完整 啊 应 会 包含 更 多 的 信息 ， 但 是 程序 清单 16.1 只 包含 了 
几 个 值得 注 意 的 元 系 。 首 先 ， 在 啊 应 的 顶部 是 名 为 activeProfiles 的 字 
段 。 在 本 例 中 ， 它 表明 development profile 处 于 激活 状态 。 如 果 还 有 其 他 
profile 处 于 激活 状态 ， 那 么 也 将 会 列 到 这 里 。 


随后 ，propertySources 字 段 是 一 个 数组 ，Spring 应 用 环境 的 每 个 属 
性 源 对 应 其 中 的 一 个 条 目 。 在 程序 清单 16.1 中 ， 只 显示 了 
SystemEnvironment 以 及 引用 application.yml 文 件 的 属性 源 。 


在 每 个 属性 源 中 ， 有 是 该 属性 源 所 提供 的 属性 的 列表 以 及 它们 的 值 。 
在 application.yml 属 性 源 中 ， 每 个 属性 的 origin 字 上 段 指明 了 该 属性 是 在 哪 
里 设置 的 ， 包 括 在 application.yml 文 件 中 的 行 号 和 列 号 。 


“env” 问 点 也 可 以 用 来 获取 特定 的 属性 ， 只 需要 将 属性 名 作为 路 和 丛 
的 第 二 个 元 系 即 可 。 例 如 ， 要 检查 server.port 属 性 ， 我 们 可 以 提交 GET 
请 求 到 “enwserver.port”， 如 下 所 示 : 





$ curl localhost:80881/actuator/env/server.port 
{ 
"property": 1{ 
"source": "systemEnvironment", Value : "80681" 
}, 
"activeProfiles": [ "development" |,， 
"propertySources": | 
{ "name": "server.ports"” }, 
{ "name": "mongo.ports"” }, 


{ "name": “SystemProperties” }, 
{ "name": "systemEnvironment", 
"property": { 


"value": “8081 ， 
"origin": System Environment Property \ SERVER_PORTAN 


} 
}, 
{ "name": "random” }, 
{ "name": "applicationConfig: [classpath:/application.yml|]",， 
"property": { 
"value": 0， 
"origin": "class path resource [application.yml|:9:9" 
} 
}, 
{ "name": "springCloudClientHostInfo"” }, 
{ "name": "refresh” }, 
{ "name": "defaultProperties"” }, 
{ "name": "Management Server"” } 


我 们 可 以 看 到 ， 这 里 依然 会 展现 所 有 的 属性 源 ， 但 是 只 有 包含 特定 
属性 的 属性 源 才 会 显示 额外 的 信息 。 在 本 例 中 ，systemEnvironment 属 性 
源 和 application.yml 属 性 产 都 包含 了 server.port 属 性 的 值 。 因 为 
systemEnvironment 属 性 源 要 优先 于 后 面 所 列 的 属性 源 ， 所 以 它 的 值 8081 
会 胜出 。 胜 出 的 值 也 会 反映 在 顶部 的 property 字 段 中 。 


不 仅 可 以 用 “env” 病 点 来 读 取 属性 的 值 ， 还 可 以 通过 同 “/env” 闹 所 
发 迹 POST 请 求 ， 同 时 提交 JSON 文 档 格 式 的 name 和 value 字 上段， 为 直 在 运 
行 的 应 用 设置 属性 。 例 如 ， 要 将 名 为 tacocloud.discount.code 的 属性 设置 
为 TACOS1234， 我 们 可 以 在 命令 行使 用 curl 提 区 POST 请 求 ， 如 下 所 


A]N 





$ curl localhost:80681/actuator/env \ 
-d'{"name":"tacocloud.discount.code","value":"TACOS1234"}' \ 
-H “Content-type: application/Jjson" 

{"tacocloud.discount.code":"TACOS1234"} 





在 提交 该 属性 之 后 ， 在 返回 的 啊 应 中 将 会 包含 新 设置 的 属性 和 它 的 
值 。 如 果 后 续 不 圾 要 这 个 属性 ， 那 么 我 们 可 以 提交 一 个 DELETE 请 求 
人 到“/eny” 咒 点， 将 通过 二 是 扣 创建 的 所 有 属性 删除 : 


$ curl localhost:80681/actuator/env -X DELETE 


{"tacocloud.discount.code":"TACOS1234"} 





通过 Actuator API 设 置 属性 是 非常 有 用 的 ， 但 是 需要 记 住所 有 通过 
向 “Jenv” 端 点 发 送 POST 请 求 设置 的 属性 只 会 用 到 接收 到 该 请 求 的 应 用 
中 ， 是 临时 的 ， 应 用 重启 的 话 就 会 丢失 。 


HTTP 有 映射 寻 视 


尽管 Spring MVC 〈 以 及 Spring WebFlux) 编程 模型 非常 易于 处 理 
HTTP 请 求 ， 我 们 只 需要 为 方法 添加 请 求 映 射 注 解 即 可 ， 但 是 我 们 很 难 
对 应 用 你 体 能 够 处 理 哪些 HITP 请 求 以 及 每 种 组 件 分 别处 理 哪 些 请 求 有 
一 个 整体 的 了 解 。 


Actuator 有 “/mappings” 闹 点 为 应 用 中 的 所 有 HTTP 请 求 处 理 融 提供 了 
一 个 一 站 式 的 视图 ， 不 管 这 些 处 理 器 是 来 自 Spring MVC 控 制 器 还 是 
Actuator 端 点 ， 我 们 都 能 一 目 了 然 地 看 清 。 要 获取 Spring Boot 应 用 中 所 
有 端点 的 完整 列表 ， 我 们 只 需要 癌 “%mappings” 发 送 一 个 GET 请 求 ， 就 会 
看 到 大 致 如 程序 清单 16.2 所 示 的 啊 应 。 


程序 清单 16.2 “mappings” 端 点 所 展示 的 HITP 映 射 


$ curl localhost:8681/actuator/mappings | jq 


"contexts": { 
"application-1": { 
"mappings": 1{ 
"dispatcherHandlers": { 
"webHandler": | 


{ 
"predicate": "{[/ingredients|,methods=[GET|}",， 


"handler": “public 
reactor.core.publisher.Flux<tacos.ingredients.Ingredient> 
tacos.ingredients.IngredientsController.allIingredients()",， 


"details": { 
"handlerMethod": { 
"className": “tacos.ingredients.IngredientsController",， 
"name": "allIngredients",， 
"descriptor": "()Lreactor/core/publisher/Flux;" 
}, 


"handlerFunction": null, 
"requestMappingConditions": { 
"consumes": [|]， 
"headers": [|]， 


"methods": | 
“GET 
] ， 
"params": | |]， 
"patterns": | 
"/ingredients" 
] ， 
"produces": | 
} 
} 
}, 
] 
} 
}, 
"parentId": “application-1" 
}, 
"bootstrap": { 
"mappings": 1{ 
"dispatcherHandlers": {} 
}, 
“parentId : null 
} 


} 


为 了 简洁， 这 个 啊 应 进行 了 删 减 ， 只 包含 了 一 个 请 求 处 理 右 。 其 体 
来 讲 ， 它 表明 对 %ingredients” 的 GET 请 求 将 由 IngredientsController 的 
allIngredients() 方 法 来 处 理 。 


常理 日 志 级 别 


对 于 任何 应 用 来 说 ， 日 志 都 是 很 重要 的 特性 。 日 志 是 一 种 审计 方 
式 ， 也 是 一 种 较为 粗略 的 调试 方法 。 


设置 日 专 级 别 是 一 种 需要 很 强 平 衡 能 力 的 事情 。 如 朱 我 们 将 日 专 级 
别 设 置 得 太 低 ， 那 么 日 总 中 会 有 太 多 的 噪声 ， 碍 找 有 用 的 信息 会 变 得 很 
困难 。 态 外 ， 如 案 我 们 将 日 专 级 列 设 置地 过 于 人 窗 滞 ， 那 么 日 志 对 于 理解 
应 用 正在 做 什么 可 能 没有 太 大 的 价值 。 


日 志 级 别 通 第 会 基于 Java 包 来 进行 设置 。 如 果 你 想 要 知道 正在 运行 
的 应 用 中 使 用 了 什么 日 六 级 别 ， 那 么 可 以 网 %loggers” 交 点 及 达 GET 请 
求 。 如 下 的 JSON 展 示 了 “/loggers” 啊 应 的 一 个 厂 段 : 





"levels": [ "OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"” |， 


"loggers": 1{ 

"ROOT™": 1{ 

"configuredLevel": “INFO", "effectiveLevel": “INFO- 
}, 
"org.springframework.web": { 

"configuredLevel": null, "effectiveLevel": “INFO- 
}, 
"tacos": { 

"configuredLevel": null, "effectiveLevel": “INFO- 
}, 


"tacos.ingredients": { 


"configuredLevel": null, effectiveLeve] : “INFO- 
}, 
"tacos.ingredients.IngredientServiceApplication": { 
"configuredLevel": null, "effectiveLevel": “INFO- 





在 啊 应 的 项 部 首先 是 所 有 合法 日 志 级 别 的 列表 。 在 此 之 后 ，loggers 
元 素 列 出 了 应 用 中 每 个 包 的 日 志 级 别 详情 。configuredLevel 属 性 展示 了 
明确 配置 的 日 志 级 别 〈( 如 末 没 有 明确 配置 的 话 ， 将 会 显示 null〉。 
effectiveLevel 属 性 展示 的 是 实际 的 日 志 级 别 ， 它 可 能 是 从 父 包 或 根 
logger 继 承 下 来 的 。 


和 


尽管 这 个 厂 段 只 展现 了 根 logger 和 4 个 包 的 日 志 级 别 ， 但 是 完整 的 啊 
应 会 包含 应 用 中 每 个 包 的 日 志 级 别 ， 包 括 我 们 所 使 用 的 库 对 应 的 包 。 如 
朱 你 只 关心 特定 的 包 ， 那 么 可 以 在 请 求 中 以 额外 路 径 组 件 的 方式 指明 包 


例如 ， 你 只 想 知 道 taco.ingredients 包 的 日 志 级 别 ， 那 么 可 以 友 送 请 
求 到 ”loggers/tacos/ ingredients”: 


{ 
"configuredLevel": null, 
"effectiveLevel": "INFO" 


} 





除了 返回 应 用 程序 中 包 的 日 志 级 列 之 外 ， 退 过 问 “/loggers” 闹 扣发 过 
POST 请 求 ， 我 们 还 能 修改 已 配置 的 日 志 级 别 。 例 如 ， 假 设 我 们 想 要 将 
taco.ingredients 包 的 日 志 级 别 设 置 为 DEBUG。 如 下 的 curl 命 令 能 够 实现 
这 一 扩 : 


$ curl localhost:8681/actuator/loggers/tacos/ingredients \ 


-d'{"configuredLevel":"DEBUG"}' \ 
-H"Content-type: application/json" 





现在 ， 日 志 级 别 已 经 友 生 了 人 变化， 我 们 可 以 
回 “/loggers/tacos/ingredients” 发 送 GET 请 求 ， 看 一 下 它 变 成 了 什么 样子 : 


| 
"configuredLevel": "DEBUG", 


"effectijveLevel"”": "DEBUG" 
} 





注意 ， 在 此 之 前 ，configuredLevel 的 值 为 null， 现 在 它 变 成 了 
DEBUG 。 这 个 变更 也 会 影响 到 effectiveLevel。 最 重要 的 是 ， 如 果 这 个 
包 中 的 代码 以 debug 级 别 打 印 日 志 ， 那 么 日 志文 件 中 将 会 包含 debug 级 别 
的 信息 。 


16.2.3 ”但 看 应 用 有 的 活动 


如 果 我 们 能 够 时 刻 监 视 运 行 中 应 用 的 活动 ， 那 将 会 非常 有 用 ， 我 们 
所 关注 的 信息 可 能 包括 应 用 正在 处 理 什 么 类 型 的 HTTP 请 求 以 及 应 用 中 
所 有 线程 的 活动 。 为 了 实现 这 一 点 ，Actuator 提 供 
了 “httptrace”“ythreaddump” 和 “heapdump” 疹 
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“heapdump” 痪 点 可 能 是 最 难以 详细 前 述 的 Actuator 疾 点 。 傈 而 言 
之 ， 它 会 下 载 一 个 gzip 压 缩 的 HPROF 堆 转 储 文件 ， 该 文件 可 以 用 来 跟踪 
内 存 和 线程 问题 。 由 于 篇 幅 的 原因 ， 青 加 上 堆 转 储 文件 的 使 用 是 一 个 非 
常 高 级 的 特性 ， 所 以 对 %heapdump” 端 点 的 介绍 就 仅 限 于 此 。 


跟踪 HTTP 活 动 


httptrace” 闪 点 能 够 报告 应 用 所 处 理 的 最 近 100 个 请 求 的 详情 。 详 情 
内 容 包 括 请 求 的 方法 和 路 人 笃 、 代 表 请 求 处 理 时 刻 的 时 间 惟 、 请 求 和 啊 应 
的 头 信息 以 及 处 理 该 请 求 的 耗 时 。 


如 下 的 JSON 片 段 展 示 了 “httptrace” 端 点 响应 的 一 个 条 目 


{ 
"traces": | 
\ 
"timestamp": “2018-66-603T23:41:24.4942 ， 
"principal": null, 
"session": null, 
"request": 1{ 
"method": "GET", 
"uri": "http://localhost:806081/ingredients",， 
"headers": { 
"Host": |[ localhost:8681 ”| ， 
"User-Agent : [curl1/7.54.6 |， 
ARCGGDE 人 TT" /| 
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"remoteAddress": null 
}, 
"response": 1{ 
"status": 200， 
"headers": { 
"Content-Type": ["application/json;charset=UTF-8"| 
} 
}, 


"timeTaken”": 4 





尽管 这 些 信息 对 调试 很 有 价值 ， 但 是 随 看 时 间 推 移 不 断 跟踪 数据 坪 
更 有 意思 的 ， 基 于 啊 应 的 状态 值 ， 它 能 够 让 我 们 洞 肾 应 用 程序 在 给 定 的 


时 间 内 有 多 少 请 求 是 成 功 的 、 有 多 少 请 求 是 失败 的 。 在 第 17 章 中 ， 我 们 
将 会 看 到 Spring Boot Admin 是 如 何 将 这 些 信息 捕获 到 一 个 运行 图 中 的 ， 
借助 这 个 图 我 们 能 够 可 视 化 一 定 的 时 间 范 围 内 的 HTTP 跟 踪 信 息 。 


监控 线程 


除了 HTTP 请 求 的 跟 躁 信息 ， 在 确定 应 用 运行 状况 的 时 候 ， 线 程 活 
动 也 是 非常 有 用 的 。“/threaddump” 并 点 能 够 生成 一 个 当前 线程 活动 的 快 
照 。 通 过 如 下 的 “threaddump” 奖 点 啊 应 片段 ， 我 们 能 够 大 致 了 解 这 个 端 
氮 都 皖 供 了 什么 功能 


"threadName": “reactor-http-nio-8 ， 
"threadId": 338, 
"blockedTime": -1， 
"blockedCount": 6， 
"waitedTime": -1, 
"waitedCount": 0， 
"lockName": null, 
"lockOwnerId": -1, 
"lockOwnerName": null, 
"inNative": true, 
"suspended": false, 
"threadState": "RUNNABLE", 
"stackTrace": | 


{ 
"methodName": "keventO",， 
"fileName": “KQueueArrayWrapper .java ， 
"lineNumber": -2， 
"className": “Sun.nlo.ch.KQueueArrayWrapper ， 
"nativeMethod": true 

}, 

{ 
"methodName": "poll",， 
"fileName": “KQueueArrayWrapper .java ， 
"lineNumber": 198, 
"className": “Sun.nlo.ch.KQueueArrayWrapper ， 


"nativeMethod": false 


}, 
]， 
"lockedMonitors": | 
"ClassName : "io.netty.channel.nio.SelectedSelectionKeySet",， 
“ IdentityHashCode : 1639768944 ， 
"lockedStackDepth": 3， 


"lockedStackFrame": { 
"methodName": "lockAndDoSelect",， 


"fileName": “ SelectorImp .Java ， 
"lineNumber": 86， 

"ClassName : “Sun.nlo.ch.SelectorImp] ， 
"nativeMethod": false 


} 
}， 


"lockedSynchronizers": [|],， 
“lockInfo": null 


} 


完整 的 线程 转 储 报告 包含 了 运行 中 应 用 的 每 个 线程 。 为 了 市 管 空 
间 ， 这 里 的 线程 转 储 进行 了 删 减 ， 只 包 侣 了 一 个 线程 条 目 。 我 们 可 以 看 
到 ， 这 里 包含 了 线程 的 阻 窗 和 锁定 状态 ， 以 及 其 他 的 线程 细节 。 这 里 还 
有 一 个 堆栈 ， 它 能 够 展现 线程 部 将 时 间 花 到 了 哪 块 代码 中 。 


因为 “/threaddump” 只 提供 了 请 求 时 线程 活动 的 快照 ， 所 以 它 很 难 完 
整 了 解 随 独 时 间 的 推移 线程 的 行为 都 是 什么 样子 的 。 在 第 17 章 中 ， 我 们 
将 会 看 到 Spring Boot Admin 如 何在 一 个 实时 视图 中 监视 “/threaddump” 闹 


16.2.4 获取 应 用 的 指标 


“/metrics” 闹 点 能 够 报告 运行 中 的 应 用 程序 所 生成 的 各 种 度量 指标 ， 


包括 天 于 内 存 、 处 理 硕 、 垃圾 收集 以 及 HTTP 请 求 的 指 标 o Actuator 提 供 
了 20 多 个 开 箱 即 用 的 指标 分 类 ， 妆 我 们 同 “/metrics” 友 运 GET 请 求 时 所 得 
到 的 指标 分 类 证 明了 这 一 点 : 


$ curl localhost:8681/actuator/metrics | jq 
{ 


"names": |[ 
"Jvm.memory .max ， 
"process.files.max'", 
"Jvm.gc.memory .promoted", 
"http.server.requests",， 
"system.l1oad.average.1m", 
"Jvm.memory.used'",， 
"Jvm.gc.max.data.size", 
"Jvm.memory .committed", 
"system.cpu.count", 
"logback.events",， 
"Jvm.buffer.memory.used",， 
"Jvm.threads.daemon", 
"system.cpu.usage'", 
"Jvm.gc.memory.allocated",， 
"Jvm.threads.1live", 
"Jvm.threads .peak",， 
"process.uptime", 
“process.cpu.usage', 
"Jvm.classes.1loaded",， 
"Jvm.gc.pause'", 
"Jvm.classes.unloaded",， 
"Jvm.gc.1live.data.size",， 
“process .fliles.open ， 
"Jvm.buffer.count", 
"Jvm.buffer.total.capacity", 
“process.start.time”" 





这 里 涉及 太 多 的 指标 ， 所 以 本 章 不 可 能 面面俱到 地 介绍 。 相 反 ， 我 
们 可 以 只 关注 一 个 指标 分 类 ， 即 http.server.requests， 以 它 作为 样 例 介绍 
如 何 消费 “/metrics” 病 点 。 


现在 ， 我 们 不 再 简单 地 请 求 %metrics”， 而 是 发 送 GET 请 求 
到 “/metrics/{METRICS CATEGORY}”， 这 样 我 们 融会 收 到 该 分 类 的 指 
标 详情 。 束 http.server.reduests 来 说 ， 我 们 有 发送 GET 请 求 到 “metrics/ 
http.server.requests” 所 返回 的 数据 如 下 所 示 : 


$ curl localhost:8881/actuator/metrics/http.server.requests 
{ 
"name": "http.server.requests",， 
"measurements": | 
{ "statistic": "COUNT", "value": 21063 }, 
{ "statistic": "TOTAL TIME", "value": 18.0686334315 }, 
{ "statistic": "MAX", "value": 606.6028926313 } 
] ， 
"availableTags": | 
"tag": exception ， 
"values": | "ResponseStatusException", 
"TllegalArgumentException", "none” | }, 
"tag": "method", "values": [ "GET" | }, 
"tag": "Uri", 
"values": | 
"/actuator/metrics/{requiredMetricName}",， 
"/actuator/health", /actuator/info ， /Ingredients ， 
"/actuator/metrics"”, "/**" | }, 
"tag": "status", "values": [ "464", "56060", "26060" | } 





这 个 啊 应 中 最 重要 的 组 成 部 分 是 measurements 区 域 ， 它 包含 了 所 请 
求 分 类 的 所 有 指标 数据 。 在 本 例 中 ， 它 表示 一 共有 2103 个 HTTP 请 求 ， 
处 理 这 些 请 求 的 总 耗 时 是 18.086334315 秒 ， 处 理 单个 请 求 的 最 大 耗 时 是 
0.028926313 秒 。 


通用 的 指标 非常 有 意思 ， 但 是 我 们 可 以 使 用 availableTags 中 所 
pn 一 步 细 化 结果 。 人 例如， 我 们 知道 一 共有 2103 个 请 求 ， 但 是 
还 不 知道 HTTP 200、HTTP 404 或 HTTP 500 响 应 状态 的 请 求 分 别 有 多 


少 。 信 助 status 标 俭 ， 我 们 可 以 得 到 所 有 状态 为 HITP 404 的 请 求 指标 : 


$ curl localhost:8881/actuator/metrics/http.server.requests? \ 
tag=status :4064 


{ 
"name": "http.server.requests",， 
"measurements": | 
{ "statistic": "COUNT", "value": 31 }, 
{ "statistic": "TOTAL TIME", "value": 6.522061212 }, 
{ "statistic": "MAX", "value": 0 } 
] ， 


"availableTags": | 
"tag": exception ， 
"values": | "ResponseStatusException", "none” | }, 
"tag": "method", "values": [ "GET" | }, 
"tag": "Uri", 
"values": | 
"/actuator/metrics/{requiredMetricName}”, "/**" | } 





通过 使 用 tag 请 求 属性 指定 标签 名 和 从 ， 我 们 可 以 看 到 所 有 啊 应 为 
HTTP 404 的 请 求 的 指标 。 这 里 显示 有 31 个 请 求 的 结果 是 404， 耗 用 了 
0.522061212 秒 。 除 此 之 外 ， 我 们 可 以 看 到 有 一 些 失 败 的 请 求 是 针 
对 “actuatormetrics/{requiredMetricsName}” 的 GET 请 求 〈 尽 管 我 们 并 不 
清楚 {requiredMetricsName} 路 径 变 量 解析 成 了 什么 ) 。 另 外 ， 有 些 是 发 
送 其 他 路 径 的 ， 是 由 ”%**? 通 配 符 捕 获 到 的 。 


如 果 我 们 想 要 知道 有 多 少 HTTP 404 响 应 是 发 送 到 “/**” 路 径 的 ， 那 
么 又 该 怎么 办 呢 ? 我 们 所 要 做 的 束 是 进一步 对 其 进行 过 滤 ， 在 请 求 中 使 
用 url 标 和 俭 ， 如 下 所 示 : 





% curl “localhost:8881/actuator/metrics/http.server.requests? \ 
tag=status:4064&tag=uri:/**" 


{ 


"name": "http.server.requests",， 


"measurements": | 
{ "statistic": "COUNT", "value": 36 }, 
{ "statistic": "TOTAL TIME", "value": 8.519791548 }, 
{ "statistic": "MAX", "value": 0 } 


"availableTags": | 
{ "tag": "exception", "values": | “ResponseStatusException” | }, 
{ "tag": "method", "values": [ "GET” | } 
] 
} 





我 们 可 以 看 到 有 30 个 路 径 丐 配 “/**” 的 请 求 得 到 了 HTTP 404， 并 且 
处 理 这 些 请 求 耗费 了 0.519791548 秒 。 


你 可 能 也 注意 到 了 ， 随 看 我 们 不 断 细 化 请 求 的 条 件 ， 可 用 的 标签 越 
来 越 有 限 。 这 里 只 列 出 了 展现 指标 所 对 应 的 请 求 能 够 适用 的 标 伦 。 在 本 
例 中 ，exception 和 method 标 合 只 有 一 个 值 。 显 然 ，30 个 请 求 都 是 GET 请 
求 ， 并 且 都 是 因为 抛 出 ResponseStatusException 而 产生 的 404 状 态 。 


导 宽 整个 %metrics” 可 能 是 一 件 很 国 烦 的 事情 ， 但 是 稍 加 练习 ， 我 们 
一 定 能 够 找到 自己 想 要 的 数据 。 在 第 17 章 中， 我 们 将 会 看 到 借助 Spring 
Boot Admin， 我 们 能 够 更 容易 地 消费 “/metrics” 病 点 的 数据 。 


尽管 Actuator 闪 点 所 提供 的 信息 有 助 于 观 穴 运 行 中 Spring Boot 应 用 
的 内 部 状况 ， 但 是 它们 并 不 适用 于 人 类 直接 使 用 。 作 为 REST 闹 点 ， 它 
们 是 供 其 他 应 用 消费 的 ， 这 里 所 说 的 其 他 应 用 也 可 能 是 UI。 考 虑 到 这 一 
扩 ， 我 们 在 第 17 章 会 看 到 如 何在 用 户 友 好 的 Web 应 用 中 展现 Actuator 信 
思 。 现 在 ， 我 们 看 一 下 如 何 目 定 义 Actuator 的 端点 。 


16.3 目 定 义 Actuator 


Actuator 最 棒 的 特性 之 一 就 是 它 能 够 进行 日 定义 ， 以 满足 应 用 的 特 
需求 。 有 一 些 问 点 本 映 文 持 目 定义 扩展 ， 同 时 Actuator 也 人 允许 我 们 创 
ig 


接 下 来 ， 我 们 看 一 下 Actuator 能 够 进行 日 定义 的 几 种 方式 。 下 而 先 
从 为 Winfo”* 端 点 添加 信息 开始 。 


16.3.1 为 </info” 闹 点 提供 信息 


正如 我 们 在 16.2.1 小 节 所 看 到 的 那样 ，“/info* 最 人 切 是 空 的 ， 没 有 提 
供 任 何 信 息 。 我 们 可 以 通过 创建 前 缀 为 “info.” 的 属性 很 容易 地 为 它 过 加 
数据 。 


尽管 创建 前 缀 为 “info.” 的 属性 是 一 个 很 测 单 的 为 Vinfo” 闪 点 深 加 目 
定义 数据 的 方式 ， 但 是 这 并 不 是 唯一 的 方式 。Spring Boot 提 供 了 名 为 
InfoContributor 的 接口 ， 人 允许 我 们 以 编程 的 方式 为 Vinfo” 交 点 添加 任何 四 
要 的 信息 。Spring Boot 甚 至 提供 了 InfoContributor 接 口 的 几 个 实现 ， 你 肯 
定 会 友 现 它们 非常 有 有 用。 


接 下 来 ， 我 们 看 一 下 如 何 编号 目 定 义 的 mfoContributor， 以 便于 
问 %info" 交 点 添加 目 定 义 的 信息 


创建 日 定义 的 Info 页 献 者 


假设 我 们 想 要 为 %info” 闪 点 这 加 关于 Taco Cloud 的 统计 信息 ， 比 如 


想 要 包含 已 经 创建 多 少 taco 有 的 信息 。 为 了 实现 这 一 点 ， 我 们 需要 编写 一 
个 实现 InfoContributor 接 口 的 类， 并 将 TacoRepository 注 入 进来 ， 然 后 发 
布 TacoRepository 提 供 的 信息 到 ”%info” 端 点 中 。 程 序 清单 16.3 展 示 了 如 何 
实现 这 样 一 个 页 献 者。 


程序 清单 16.3 ”InfoContributor 的 目 定 义 实 现 


package tacos.tacos,; 

Import org.springframework.boot.actuate.info.InfoContributor; 
import org.springframework.stereotype.Component; 

Import java.util.HashMap,; 

Import java.util.Map; 

Import org.springframework.boot.actuate.info.Info.Builder; 


QComponent 
public class TacoCountInfoContributor implements InfoContributor { 
private TacoRepository tacoRepo; 


public TacoCountInfoContributor(TacoRepository tacoRepo) { 
this.tacoRepo = 七 CORepo ; 


} 


QOverride 

public void contribute(Builder builder) { 
long tacoCount = tacoRepo.count(); 
Map<String, Object> tacoMap = new HashMap<String, Object>(); 
tacoMap.put("count", tacoCount); 
builder.withDetail("taco-stats", tacoMap); 


} 





要 实现 InfoContributor 接 口 ，TacoCountInfoContributor 束 需要 实现 
contribute() 方 法 。 这 个 方法 能 够 得 到 一 个 Builder 对 象 ， 基 于 这 个 对 象 ， 
contribute(O) 调 用 withDetail0 方 法 来 添加 详情 信息 。 在 上 述 的 实现 中 ， 我 
们 通过 TacoRepository 的 countO 来 获取 已 经 创建 了 多 少 个 taco。 然 后 ， 我 
们 将 这 个 数量 放 到 一 个 Map 中 ， 以 值 为 taco-stats 的 label 将 它 传递 到 


builder 中 。 这 样 形成 的 “/info” 冲 后 将 会 包含 这 个 数量 ， 如 下 所 示 : 


{ 


"taco-stats": { 
"count": 44 


} 


} 





我 们 可 以 看 到 ，InfoContributor 的 实现 可 以 以 任何 方式 页 献 信息 。 
为 属性 深 加 “info.” 前 缀 虽然 简单 ， 但 是 它们 却 只 能 是 静态 值 。 


注入 构建 信息 到 “info” 疹 点 中 


Spring Boot 提 供 了 一 些 内 置 的 InfoContributor 实 现 ， 它 们 能 够 自动 添 
加 信息 到 %info" 闪 点 的 结 来 中。 其 中 有 一 个 实现 是 
BuildInfoContributor， 它 能 够 将 项 目 构建 文件 中 的 信息 洪 加 a 到 “info” 闹 
点 的 结果 中 。 这 包括 了 一 些 基 本 信息 ， 比 如 项 目 版 本 、 构 建 的 时 间 惟 以 
及 执行 构建 的 主机 和 用 户 。 


为 了 将 构建 信息 添加 到 %info” 痪 氮 的 结 末 中， 我 们 需要 添加 build- 
info goal 到 Spring Boot Maven Plugin executions 中 ， 如 下 上 所 示 : 





<build> 
<plugins> 
<plugin> 
<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-maven-plugin</artifactId> 
<executions> 
<execution> 
<goals> 
<goal>build-info</goal> 
</goals> 
</execution> 
</executions> 


</plugin> 
</plugins> 
</build> 


如 果 使 用 Gradle 构 建 项 目 ， 我 们 只 需要 添加 如 下 几 行 代码 到 
build.gradle 文 件 中 : 
springBoot { 


buildInfo() 
} 


个 管 是 哪 种 方式 ， 构 建 过 程 都 会 在 可 分 肥 的 JAR 或 WAR 文 件 中 生成 
一 个 名 为 build-info.properties 的 文件 ，BuildInfoContributor 会 使 用 这 个 
件 并 为 “info”* 闹 点 页 献 信息 。 如 下 的 “/info” 尊 点 啊 应 厂 段 展现 了 所 页 献 
的 构建 信息 : 


"build": { 
"version": "0.0.16-SNAPSHOT",， 
"artifact": “ingredient-service'",， 


"name": "ingredient-service",， 
"group": “S1a5 ， 
"time”": "206018-66-64T1060:24:64.3732Z" 





言 忆 ee 行 的 应 用 的 确切 版 本 和 构建 时 间 古 非 
音 有 有 肯 过 癌 %/info” 疝 点 肥 友 GET 请 求 ， 我 们 束 能 知 章 正在 运行 的 
征 不 是 项 目的 Ren 


骏 露 Git 提 A 克 信 筷 4 


假设 我 们 的 项 目 使 用 Git 进 行 产 但 控制 ， 那 么 我 们 可 以 在 %info” 病 局 


中 包含 Git 提 交 人 信息。 为 了 实现 这 一 点 ， 我 们 需要 这 加 如 下 的 插件 到 
Maven 项 目的 pom.xml 文 件 中 : 


<build> 
<plugins> 


<plugin> 


<groupId>pl.project13.maven</groupId> 
<artifactId>git-commit-id-plugin</artifactId> 
</plugin> 
</plugins> 
</build> 





如 果 你 是 Gradle 用 户 ， 也 不 用 担心 ， 我 们 可 以 将 一 个 功能 相同 的 插 
件 放 到 build.gradle 文 件 中 : 


plugins { 


id "com.gorylenko.gradle-git-properties" version "1.4.17" 





} 
这 两 个 插件 完成 的 是 相同 的 事情 : 它们 会 生成 一 个 名 为 
git.properties 的 构建 期 制 件 ， 这 个 文件 包含 了 项 目的 所 有 Git 元 数据 。 在 
运行 时 ， 有 个 特殊 的 mfoContributor 实 现 能 够 发 现 这 个 文件 并 将 它 的 内 


容 页 献 给 "info” 病 点 。 


按照 最 简单 的 形式 ，%info" 冰 点 展现 的 Git 信 息 包 括 应 用 构建 所 使 用 
的 Git 分 文 、 提 区 的 哈 希 信 以 及 时 间 鹤 : 





"time": “2018-06-02T18:16:582 ， 
"id": "b5c164d" 


"branch": "master”" 


]}， 





A ER 


这 些 信息 非 第 确定 地 揪 述 了 项 目 构 建 时 代码 的 状态 。 但 是 ， 我 们 还 
可 以 将 management.info.git.mode 属 性 设置 为 full: 


management: 
info: 


2it: 
mode: full 





这 样 我 们 就 能 得 到 项 目 构 建 时 非常 详尽 的 Git 提 交 信 息 。 程 序 清单 
16.4 展 现 了 完整 Git 信 息 的 一 个 样 例 。 


程序 清单 16.4” 通过 “/info”* 端 点 展现 完整 的 Git 信 息 


{ 
“glIt : 1{ 
"build": { 
"host": "DarkSide.local",， 
"version": "60.060.16-SNAPSHOT",， 
"time”": "206018-66-62T18:11:232"， 


"user": { 
"name": "Craig Walls", 
"email": "craig@habuma.com" 
} 
已 
"branch": master ， 


"commit™: { 
"message": 1{ 
"short": Add Spring Boot Admin and Actuator", 
"full": “Add Spring Boot Admin and Actuator" 


"id": 1{ 
"describe": “b5c164d-dirty ， 
“abbrev : “b5c164d ， 
“ describe-short : “b5c1604d-dirty ， 
"full": “b5c164d1fcbe6c2b84965ea68a336595166fd44e - 


十 Ime : “2018-06-02T18:16:582 ， 


"user": { 


"email": "craigQ@habuma.com", 
"name": "Craig Walls" 
}, 
"closest": 1{ 
"tag": { 
“name : ™" 
"commit": { 
“COunt : ™" 
} 
} 


2 
"dirty": "true'", 
"remote™": { 
"origin": { 
"url": "Unknown”" 


} 


2 
"tags": 是 


除了 时 间 崔 和 Git 所 交 哈 希 值 的 缩 略 什 ， 完 整 版 本 的 信息 还 包 人 台 了 
代码 提 交 者 的 名 字 和 和 邮箱、 完整 的 提交 信息 和 其 他 内 容 ， 这 样 我 们 束 能 
精确 定位 构建 项 目 所 使 用 的 代码 。 实 际 上 ， 我 们 可 以 看 到 程序 清早 16.4 
中 dirty 属 性 的 值 为 tue， 表 明 在 项 目 构建 时 构建 目录 中 和 存在 未 提交 的 变 
更 。 没 有 什么 信息 比 这 更 有 说 服 力 了 ! 


16.3.2 ”实现 和 目 定义 的 健康 指示 桥 
Spring Boot 提 供 了 多 个 内 置 的 健康 指示 需 ， 它 们 能 够 提供 与 Spring 


应 用 进行 交互 的 通用 外 部 系统 的 健康 信息 。 有 时 候 你 可 能 会 及 现 ， 你 所 
使 用 的 外 部 系统 在 Spring Boot 的 预料 之 外 ，Spring Boot 也 没有 为 它 提 供 


健康 指示 大 。 例 如 ， 你 的 应 用 可 能 与 一 个 遗留 的 大 型 机 应 用 进行 交互 ， 
应 用 的 健康 状况 可 能 会 受到 遗留 系统 健康 状况 的 影响 。 为 了 创建 目 定 义 
的 健康 指示 堪 ， 我 们 需要 做 的 承 是 创建 一 个 实现 了 HealthIndicator 接 口 
的 bean。 


实际 上 ，Taco Cloud 服 务 没有 必要 创建 目 定 义 的 健康 指示 器 ， 
Spring Boot 所 提供 的 指示 器 融 足够 用 了 。 为 了 兰 述 如 何 开 及 上 自 定 义 的 健 
康 指示 需 ， 我 们 看 一 下 程序 清单 16.5。 它 展现 了 一 个 简单 的 
HealthIndicator 实 现 ， 健 康 状况 由 每 天 中 的 时 间 所 决定 。 


程序 清单 16.5 ”HealthIndicator 的 一 个 特殊 实现 


package tacos.tacos,; 

Import java.util.Calendar.; 

Import org.springframework.boot.actuate.health.Health; 

Import org.springframework.boot.actuate.health.HealthIndicator; 
import org.springframework.stereotype.Component; 


QComponent 
public class WackoHealthIndicator 
implements HealthIindicator { 
QOverride 
public Health health() { 
int hour = Calendar.getInstance() .get(Calendar.HOUR OF DAY); 
if (hour > 12) { 
return Health 
.OUtOfServicel) 
.withDetail("reason", 
"I'm out of service after lunchtime") 
.withDetail("hour", hour) 
.build( ); 
} 


if (Math.random() < 6.1) { 
return Health 
. down() 
.withDetail("reason", "I break 16% of the time") 
.build( ); 


} 


return Health 
‘Up() 
.withDetail("reason", "All] is good!") 
.build(); 





这 个 状 狂 的 健康 指示 器 首先 会 判断 当前 是 什么 时 间 。 如 果 是 下 午 ， 
那么 所 返回 的 健康 状态 是 OUT_OF_SERVICE， 其 中 还 包含 导致 该 状态 
的 原因 详情 。 即 便 是 在 午饭 前 ， 这 个 健康 指示 器 也 有 10% 的 概率 报告 
DOWN 状 态 ， 因 为 它 使 用 随机 数 来 决定 应 用 是 否 正 第 局 动 。 如 条 随 机 数 
的 值 小 于 0.1， 那 么 状态 将 是 DOWN， 人 否则 状态 将 是 UP。 


显然 ， 在 真正 的 应 用 中 ， 程 序 清 单 16.5 的 健康 指示 故人 不 会 有 什么 用 
处 。 但 是 ， 可 以 假设 一 下 ， 我 们 不 是 根据 当前 时 间或 随机 数 ， 而 是 对 外 
部 系统 及 起 一 个 远程 调用 ， 并 基于 接收 到 的 啊 应 状态 来 进行 判定 ， 这 样 
的 话 它 束 古 一 个 非 第 有 用 的 健康 指示 融 了 了。 


16.3.3 ”注册 目 定 义 的 指标 


在 16.2.4 小 节 中 ， 我 们 看 到 了 如 何 访 问 “metrics” 冰 点 来 消费 Actuator 
发 布 的 各 种 指标 ， 当 时 我 们 主要 关注 了 HTTP 请 求 的 信息 。Actuator 提 供 
的 指标 非常 有 用 ， 但 是 “metrics” 站 点 的 结果 并 不 局 限于 内 置 的 指标 。 


实际 上 ，Actuator 的 指标 是 由 Micrometer 实 现 的 。 这 是 一 个 供应 商 
中 立 的 指标 门面 ， 借 助 它 ， 我 们 能 够 发 送 任意 想 要 的 指标 ， 并 在 所 选 的 
第 三 方 监 控 系 统 中 对 其 进行 展现 。 它 提供 了 对 Prometheus、Datadog 利 


New Relic 等 系统 的 支持 。 


使 用 Micrometer 友 布 指标 的 最 基本 方式 古 售 助 Micrometer 的 
MeterRegistry。 在 Spring Boot 应 用 中 ， 要 及 布 指 标的 话 ， 我 们 唯一 需要 
做 的 惑 是 将 MeterRegistry 广 入 到 想 要 有 发布 计 数 硕 、 计 时 硕 和 计量 需 

(gauges) 的 地 方 ， 这 些 地 方 能 够 捕获 应 用 的 指标 信息 。 


作为 发 布 目 定义 指标 的 样 例 ， 假 设 我 们 想 要 统计 不 同 配料 所 创建 的 
taco 的 数量 。 也 驳 和 是 说 ， 我 们 想 要 知道 ， 使 用 生 洲 、 雁 牛肉 、 合 西 可 溥 
饼 以 及 其 他 配料 分 别 制作 了 多 少 个 taco。 程 序 清 单 16.6 中 的 TacoMetrics 
bean 展 示 了 如 何 使 用 MeterRegistry 来 收集 信息 。 


程序 清单 16.6 ”TacoMetrics 注 册 了 关于 taco 配 料 的 指标 


package tacos.tacos,; 

import JjJava.util.List,; 

import 
org.springframework.data.rest.core.event.AbstractRepositoryEventliste 

ner 
) 

Import org.springframework.stereotype.Component,; 

Import io.micrometer.core.instrument.MeterRegistry; 


QComponent 
public class TacoMetrics extends AbstractRepositoryEventListener<Taco> { 
private MeterRegistry meterRegistry; 
public TacoMetrics(MeterRegistry meterRegistry) { 
this.meterRegistry = meterRegistry; 


} 


QOverride 
protected void onAfterCreate(Taco taco) { 
List<Ingredient> ingredients = taco.getIngredients() ; 
for (Ingredient ingredient : ingredients) { 
meterRegistry.counter("tacocloud", 
"ingredient", ingredient.getId()).increment(); 


站 
} 

我 们 可 以 看 到 ，TacoMetrics 明 过 其 构造 颖 注入 了 MeterRegistry。 它 
还 扩展 了 AbstractRepositoryEventListener， 这 是 Spring Data 中 的 一 个 类 ， 
能 够 拦截 repository 事 件 。 我 们 重 写 了 onAfterCreate() 方 法 ， 这 样 每 当 保 
存 新 的 Taco 对 象 时 都 会 得 到 通知 。 


在 onAfterCreateO0 中 ， 我 们 为 每 种 配料 声明 了 一 个 计数 项 ， 其 中 标 
签名 为 ingredient， 标 签 值 为 配料 ID。 如 果 给 定 标 签 的 计数 器 已 经 存在 ， 
就 会 午 用 已 有 的 计数 器 。 计 数 器 会 不 断 递 增 ， 表 明 使 用 该 配料 又 创建 了 


一 个 taco。 


在 创建 完 几 个 taco 之 后 ， 我 们 就 可 以 查询 “/metrics” 六 点 来 获取 配料 
的 计数 信息 了。 对 “/metrics/tacocloud”* 发 送 GET 请 求 将 会 生成 如 下 未 经 
过 滤 的 指标 数据 : 


$ curl 1ocalhost :8687/actuator/metrics/tacocloud 

{ 
"name : "tacocloud", 
"measurements": | { "statistic": "COUNT”, "value": 84 } 
] 


vailableTags": | 


{ 
"tag": Ingredlient ， 
"values": | "FLTO", "CHED", "LETC", "GRBF", 
"COTO", "JACK", "TMTO", "SLSA"| 





measurements 下 的 数值 并 没有 太 大 的 用 处 ， 它 代表 了 所 有 配料 的 总 
数 。 但 是 ， 如 果 你 想 要 知道 使 用 墨西哥 溥 饼 (FLTO) 创建 了 多 少 个 


taco， 那 么 我 们 可 以 将 ingredient 标 签 的 值 设置 为 FLTO: 


$ curl localhost:80687/actuator/metrics/tacocloud?tag=ingredient:FLTO 


{ 


"name": "tacocloud",， 
"measurements": | 
{ "statistic": "COUNT", "value": 39 } 


] ， 
"availableTags": | 





} 


现在 ， 我 们 可 以 清楚 地 看 到 ， 有 39 个 taco 是 使 用 墨西哥 薄饼 作为 其 
中 的 一 道 配料 创建 的 。 


16.3.4 ”创建 目 定 义 的 病 所 


乍 看 上 去 ， 你 可 能 会 认为 Actuator 闹 点 不 em 用 Spring MVC 的 控 
制 器 实现 的 ， 但 是 在 第 18 音 中 你 将 会 发 现 ， 这 些 端点 除了 通过 HTTP 请 
求 暴 露 之 外 ， 还 暴露 成 JMX MBean。 因 此 ， 它 们 肯定 不 仅仅 是 控制 器 类 


实际 上 ，Actuator 痪 点 的 定义 与 控制 闫 有 很 大 的 舌 卉 。Actuator 桨 操 
并 不 是 使 用 @Controller 或 @RestController 注 解 来 标注 类 ， 而 是 通过 为 类 
还 加 @Endpoint 注 解 来 实现 的 。 


男 外 ， 它 们 不 是 使 用 HTTP 方 法 命名 的 注解 ， 如 @GetMapping、 
(@PostMapping 或 @DeleteMapping，Actuator 噶 点 的 操作 是 退 过 为 方法 湛 
将 @WiriteOperation 和 @DeleteOperation 注 解 实 现 的 。 

这 些 注解 并 没有 指明 任何 的 通信 机 制 ， 实 际 上 ， 这 允许 Actuator 与 各 种 


各 样 的 通信 机 制 协作 ， 内 置 了 对 HITP 和 JMX 的 文 持 。 


为 了 阐述 如 何 编写 自 定义 的 Actuator， 参 见 程序 清单 16.7 中 的 
NotesEndpoint。 


程序 清单 16.7“” 用 来 记 笔 记 的 自 定 义 端 点 


package tacos.ingredients; 

import JjJava.util.ArrayList; 

import java.util.Date,; 

import JjJava.util.List,; 

import org.springframework.boot.actuate.endpoint.annotation.DeleteOperatio 


import org.springframework.boot.actuate.endpoint.annotation.Endpoint; 
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation; 
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation 


import org.springframework.stereotype.Component; 
Import lombok.Getter; 
Import lombok.RequiredArgsConstructor; 


QComponent 
QEndpoint(id="notes", enableByDefault=true) 
public class NotesEndpoint 1{ 


private List<Note> notes = new ArrayList<>() 


QReadOperation 

public List<Note> notes() { 
return notes ; 

} 

Q@WriteOperation 

public List<Note> addNote(String text) { 
notes.add(new Note(text)); 
return notes ; 


} 


QDeleteOperation 
public List<Note> deleteNote(int index) { 
if (index < notes.size()) { 
notes.remove(index); 


} 


return notes ; 


} 


QRequiredArgsConstructor 
private class Note { 
QGetter 
private Date time = new Date() ; 


QGetter 
private final String text; 
} 
} 





这 是 一 个 非 弟 简单 的 记 笔 记 的 交点 ， 我 们 可 以 通过 写 入 操作 提交 笔 
记 ， 通 过 读 取 操作 阅读 笔记 列表 并 且 通 过 删除 操作 移 除 菜 个 笔记 。 不 得 
不 承认 ， 这 个 问 点 并 不 像 Actuator 的 员 扣 那样 有 用 。 但 是 考虑 到 开 箱 即 
用 的 Actuator 闹 点 提供 了 如 此 众多 的 功能 ， 所 以 很 难 设 想 一 个 目 定 义 
Actuator 绒 友 的 实际 样 例 。 


不 管 怎么 说 ，NotesEndpoint 类 使 用 了 @BComponent 注 解 ， 这 样 它 会 
伞 Spring 的 组 件 扫 摘 所 及 现 ， 并 将 其 初始 化 为 Spring 应 用 上 下 文中 的 
bean。 但 是 ， 与 我 们 的 讨论 关联 最 大 的 事情 是 它 还 使 用 了 @Endpoint 注 
解 ， 使 其 成 为 一 个 有 D 为 notes 的 Actuator 绒 点 。 它 默认 束 是 启用 的 ， 所 以 
我 们 不 需要 在 management.web.endpoints.web.exposure.include 配 置 属性 中 
显 式 局 用 它 。 


可 以 看 到 ，NotesEndpoint 提 供 了 各 种 类 型 的 操作 。 


。 notes() 方 法 使 用 了 @ReadOperation 注 解 。 当 它 被 调用 的 时 候 ， 将 会 
返回 一 个 可 用 笔记 的 列表 。 按 照 HTTP 的 术语 ， 这 意味 着 它 会 处 理 
针对 “actuatornotes” 的 HITP GET 请 求 并 返回 JSON 格 式 的 笔记 列 
表 。 


。 addNote() 方 法 使 用 了 @WriteOperation 注 解 。 当 它 被 调用 的 时 候 ， 
将 会 根据 给 定 的 文本 创建 一 个 新 的 笔记 并 添加 到 列表 中 。 按 照 
HTTP 的 术语 ， 它 处 理 POST 请 求 ， 请 求 体 中 是 一 个 包含 text 属 性 的 
JSON 对 象 。 最 后 ， 它 会 在 啊 应 中 返回 当前 笔记 列表 的 状态 。 

。 deleteNote() 方 法 使 用 了 @DeleteOperation 注 解 。 当 它 被 调用 的 时 
候 ， 将 会 根据 给 定 的 索引 删除 一 条 笔记 。 按 照 HITP 的 术语 ， 这 个 
师 点 会 处 理 DELETE 请 求 ， 其 中 索引 是 通过 请 求 参 数 设 置 进来 的 。 


为 了 看 一 下 它 的 实际 效果 ， 我 们 可 以 使 用 cun 测 试 新 的 端点 。 首 
先 ， 使 用 两 个 单独 的 POST 请 求 ， 添 加 两 条 笔记 : 


$ curl localhost:806806/actuator/notes \ 

-d'{"text":"Bring home milk"}' \ 

-H"Content-type: application/Jjson" 
[{"time":"2018-66-68T13:56:45.685+66066", "text":"Bring home milk"}|] 


$ curl localhost:806806/actuator/notes \ 

-d'{"text":"Take dry cleaning"}' \ 

-H"Content-type: application/Jjson" 
[{"time":"2018-66-68T13:5060:45.685+06606060", "text":"Bring home milk"}, 
{"time":"2018-66-68T13:506:48.6021+66606", "text":"Take dry cleaning"}| 





我 们 可 以 看 到 ， 每 当 新 增 笔 记 的 时 候 ， 奖 点 都 会 返回 增加 新 内 容 之 
后 的 笔记 列表 。 如 条 想 权 奏 看 笔记 列表 ， 我 们 可 以 及 送 一 个 简单 的 GET 
请 求 : 


$ curl localhost:8060806/actuator/notes 


[{"time":"2018-66-68T13:5060:45.685+066060060", "text":"Bring home milk"}, 
{"time":"2018-66-68T13:506:48.621+6606060", "text":"Take dry cleaning"}| 





如 果 决 定 移 除 其 中 的 某 条 笔记 ， 那 么 我 们 可 以 发 送 一 个 DELETE 请 
求 ， 并 将 index 作 为 请 求 参 数 : 


区 curl] localhost:806806/actuator/notes?index=1 -X DELETE ] 


[{"time":"2018-66-68T13:506:45.685+6606060", "text":"Bring home miIlLKk 上] 





很 重要 的 一 点 就 是 ， 尽 管 我 只 展现 了 如 何 使 用 HTTP 与 端点 交互 ， 
但 是 它们 还 会 又 露 为 MBean， 我 们 可 以 使 用 任意 的 JMX 和 客户 痛 来 进行 访 
问 。 如 有 果 你 只 想 骏 露 HTTP 疹 点 ， 那 么 可 以 使 用 @WwebEndpoint 广 解 而 不 
是 @Endpoint 来 标注 病 点 类 : 


QComponent 
QWebEndpoint(id="notes", enableByDefault=true) 


public class NotesEndpoint 1{ 





} 


类 似 的 ， 如 果 你 只 想 其 露 MBean 疹 点， 那么 可 以 使 用 @JmxEndpoint 
注解 进行 标注 。 


16.4 保护 Actuator 


我 们 可 能 不 想 让 别人 宁 探 Actuator 又 露 的 信息 。 另 外 ， 因 为 Actuator 
提供 了 一 些 操作 来 修改 环 声 变 量 和 日 志 级 别 ， 所 以 最 好 对 Actuator 进 行 
保护 ， 只 有 有 具有 对 应 权限 的 和 铬 户 闹 才 能 消费 这 些 病 点 。 


虽然 你 护 Actuator 噶 点 非常 重要 ， 但 是 安全 性 本 里 并 不 是 Actuator 的 
职 贡 ， 我 们 需要 使 用 Spring Security 来 保护 Actuator。 因 为 Actuator 曾 点 
的 路 人 径 和 应 用 本 时 的 路 人 径 非 第 相似 ， 所 以 保护 Actuator 与 你 护 其 他 的 应 
用 跤 任 并 没有 什么 区 列 。 我 们 在 第 4 章 讨论 的 内 容 依 然 适 用 于 保护 


Actuator 闹 点 。 


为 所 有 的 端点 都 集中 在 “/actuator” 基 础 路 径 〈( 如 果 设 置 了 


management.endpoints.web.base-path 属 性 ， 那 么 可 能 会 是 其 他 的 路 径 ) 
下 ， 所 以 很 容易 将 授权 规则 应 用 到 所 有 的 Actuator 冰 点 上 。 例 如 ， 只 有 
具有 ROLE_ADMIN 权 限 的 用 户 才 能 调用 Actuator 端 点 ， 那 么 我 们 可 以 重 
写 WebSecurityConfigurerAdapter 的 configure(0) 方 法 : 


QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 
.authorizeRequests'( ) 
.antMatchers("/actuator/**").hasRole("ADMIN") 


.and() 


.httpBasic() ; 





这 需要 所 有 的 请 求 均 由 具备 ROLE _ ADMIN 权限 的 授权 用 户 发 起 ， 
才能 进行 访问 。 它 还 配置 了 HTTP basic 认 证 ， 这 样 客 户 端 应 用 可 以 在 请 
求 的 Authorization 头 信息 中 提交 编码 后 的 认证 信息 。 


体 护 Actuator 的 唯一 问题 在 于 ， 痪 点 的 路 径 硬 编码 为 %actuator#s#”， 
如 果 因 为 修改 了 management.endpoints.web.base-path 属 性 发 生变 化 的 
话 ， 那 么 这 种 方式 束 无 法 正常 运行 了。 为 了 帮助 解决 这 个 问题 ，Spring 
Boot 提 供 了 EndpointRequest〔 一 个 请 求 岂 配 类 ， 更 人 简单， 而 且 不 依赖 于 
给 定 的 String 路 径 ) 。 借 助 EndpointRequest， 我 们 可 以 将 相同 的 安全 要 
求 用 到 Actuator 上 ， 而 且 不 需要 便 编 鸽 路径: 





QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 
.requestMatcher(EndpointRequest.toAnyEndpoint()) 
.authorizeRequests() 
.anyRequest().hasRole("ADMIN") 


.and ( ) 
.httpBasic() ; 





EndpointRequest.toAnyEndpointO 方 法 会 返回 一 个 请 求 抱 配 硕 ， 它 会 
匹配 所 有 的 Actuator 玫 点 。 如 有 果 你 oi 
除 ， 那 么 我 们 可 以 调用 excluding0) 方 法 ， 通 过 名 称 进 行 声明 : 


QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 
.requestMatcher( 
EndpointRequest.toAnyEndpoint() 
.excluding("health", "info")) 
.authorizeRequests'( ) 
.anyRequest().hasRole("ADMIN") 
.and() 
.httpBasic() ; 





另外 ， 如 果 我 们 只 是 想 将 安全 性 用 到 其 中 一 部 分 Actuator 端 点 中 ， 
那么 可 以 调用 to0 来 蔡 换 toAnyEndpoint0， 并 使 用 名 称 指 明 这 些 端点 : 


QOverride 
protected void configure(HttpSecurity http) throws Exception { 
http 
.requestMatcher(EndpointRequest.to( 
"beans", "threaddump", "loggers")) 


.authorizeRequests() 
.anyRequest().hasRole("ADMIN") 
.and() 
.httpBasic() ; 





这 样 会 限制 只 将 安全 性 功能 
全 “</beans”“/threaddump” 和 “/loggers” 并 点 上 上 上， 其 他 的 Actuator 闹 点 会 全 部 
对 外 开放 。 


16.5 “小结 


。 Spring Boot Actuator 以 HTTP 和 JMX MBean 的 形式 提供 了 多 个 病 
点 ， 它 们 能 够 让 我 们 探查 Spring Boot 应 用 内 部 的 运行 状况 。 

。 大 多 数 的 Actuator 闪 点 默认 是 鞭 用 的 ， 我 们 可 以 通过 设置 
management.endpoints.web.exposure.include 和 
management.endpoints.web.exposure.exclude 属 性 有 选择 地 对 外 骏 
路。 

e。 有 些 端点 ， 比 如 %loggers” 和 “env”， 人 允许 写 入 操作 ， 这 样 能 够 在 运 
行 时 改变 应 用 的 配置 。 

。 价 助 %/info” 问 点 可 以 暴露 应 用 的 构建 和 和 Git 提交 的 评 情 。 

。 目 定义 的 健康 指示 颖 可 以 反映 应 用 的 健康 状况 ， 以 便于 跟 中 外 部 集 
成 系统 的 健康 状态 。 

。 自 定义 的 应 用 指标 可 以 通过 Micrometer 进 行 注 册 ， 让 Spring BootY 
用 与 多 种 流行 的 指标 引擎 进行 集成 ， 包 括 Datadog、New Relic 和 
Prometheus 。 

e。 Actuator 的 Web 端 点 可 以 通过 Spring Security 进 行 保 护 ， 与 Spring 
Web 应 用 的 其 他 闹 点 非常 相似 。 


第 17 草 ”管理 Spring 


搭建 Spring Boot Admin 


注册 客户 六 应 用 
使 用 Actuator 并 点 


保护 Admin 服 务 器 





“一 图 胜 千 言 ”， 对 于 很 多 应 用 程序 的 用 户 来 说 ， 一 个 用 户 友好 的 
Web 应 用 要 胜 过 上 于 个 API 调 用 。 不 要 误会 我 的 意思 ， 我 是 一 个 命令 行 
爱好 者 ， 非 常 喜 欢 使 用 curl 和 HTTPie 消 费 REST API。 但 是 有 时 候 先 手动 
输入 命令 行 来 调用 REST 闹 点 再 人 码 看 结果 要 比 在 浏览 器 中 点 击 链接 并 阅 
恋 结 末 低 效 得 多 。 

在 前 面 的 草 下 中 ， 我 们 探索 了 Spring Boot Actuator 和 又 露 的 所 有 HTTP 


闹 点 。 病 点 返回 的 是 JSON 啊 应 ， 所 以 对 于 如 何 使 用 它们 并 没有 任何 限 
制 。 在 本 章 中 ， 我 们 将 会 看 到 基于 Actuator 端 点 构建 的 前 端 用 户 界 面 


(CUI) ， 从 而 使 这 些 闪 点 更 易于 使 用 ， 而 且 有 些 实时 数据 是 很 难 直 接 通 
过 调用 Actuator 使 用 的 。 


17.1 使 用 Spring Boot Admin 


我 曾经 被 问 到 很 多 次 ， 开 及 一 个 消费 Actuator 听 点 的 Web 应 用 并 为 
其 提供 一 个 易于 查看 的 UI 到 底 有 多 么 难 ， 这 样 是 否 有 意义 。 我 的 答复 是 
它 只 是 一 个 REST API， 因 此 所 有 的 事情 都 是 有 可 能 的 。 不 过 ， 当 位 于 
德国 的 软件 和 咨询 公司 codecentric AG 的 优秀 工程 师 已 经 完成 了 这 项 工 
作 时 ， 我 们 为 什么 还 要 为 Actuator 创 建 自己 的 UI 呢 ? 


Spring Boot Admin 是 一 个 官 理 类 的 Web 前 闹 应 用 ， 使 得 Actuator 的 
问 点 更易 于 被 人 类 所 使 用 。 它 分 为 两 个 主要 的 组 件 : Spring Boot Admin 
服务 器 和 它 的 客 尸 疡 。Admin 服 务 器 负责 收集 并 展现 Actuator 数 据 ， 而 
展现 的 数据 则 是 由 一 个 或 多 个 Spring Boot 应 用 提供 的 ， 这 些 应 用 束 是 
Spring Boot Admin 的 客户 颖 ， 如 图 17.1 所 示 。 
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图 17.1 Spring Boot Admin 的 服务 器 消费 来 目 一 个 或 多 个 Spring Boot 应 用 的 Actuator 闹 点 ， 并 将 
数据 展现 在 一 个 基于 Web 的 UI 中 


我 们 需要 将 组 成 Taco Cloud 的 每 个 应 用 《微服 务 ) 注册 为 Spring 
Boot Admin 的 客户 顺 。 首 先 ， 我 们 需要 挫 建 Spring Boot Admin 服 务 规 ， 
以 便于 接收 每 个 客户 总 的 Actuator 信 息 。 


17.1.1 创建 Admin 有 上 服务器 


为 了 局 用 Admin 服 务 硕 ， 我 们 首先 需要 创建 一 个 新 的 Spring Boot 心 
用 并 将 Admin 服 务 右 依赖 添加 a 到 项 目的 构建 文件 中 。Admin 服 务 问 通 委 
会 作为 一 个 蛙 独 的 应 用 ， 与 其 他 的 应 用 区 分 开 来 。 因 此 ， 最 简 蛙 的 方式 
束 是 使 用 Spring Boot Initializr 创 建 一 个 新 的 Spring Boot 项 目 并 选择 标签 
为 Spring Boot Admin (Servem 的 复 选 枉 。 这 样 会 将 如 下 的 依赖 添加 到 


<dependencies> 代 码 块 中 : 


<dependency> 
<groupId>de.codecentric</groupId> 


<artifactId>spring-boot-admin-starter-server</artifactId> 
</dependency> 





现在 ， 我 们 需要 局 用 Admin 服 务 硕 ， 只 需要 在 主 配置 关上 添加 
@EnableAdminServer 广 解 殴 可 以 了 ， 如 下 所 示 : 


package tacos.bootadmin; 

Import org.springframework.boot.SpringApplication; 

Import org.springframework.boot.autoconfigure.SpringBootApplication,; 
Import de.codecentric.boot.admin.server.config.EnableAdminServer.; 


@SpringBootApplication 
@EnableAdminServer 
public class BootAdminServerApplication { 
public static void main(String[] args) { 
SpringApplication.run(BootAdminServerApplication.class, args); 





最 后 ， 因 为 在 开 友 阶段 Admin 服 务 右 并 不 是 唯一 一 个 在 本 地 运行 的 
应 用 ， 上 所 以 我 们 需要 将 其 设置 为 监听 一 个 唯一 的 端口 ， 而 且 这 个 端口 要 
易于 访问 《〈 比 如， 不 能 是 0) 。 在 这 里 ， 我 选择 9090 作 为 Spring Boot 
Admin 服 务 硕 的 姗 口 : 


server : 
port: 9090 


注意 : 与 其 他 微服 务 架 构 的 Spring Boot 应 用 类 似 ， 


server.port 可 以 在 生产 环境 的 profile 使 用 不 同 的 病 口 ， 在 那 时 交口 





可 能 会 由 撒 层 平台 来 决定 。 


现在 ， 我 们 的 Admin 服 务 亏 已 经 准备 承 绪 。 如 条 此 时 局 动 应 用 并 在 
浏览 厚 中 访问 http:/localhost:9090， 那 么 我 们 将 会 看 到 如 图 17.2 所 示 的 效 
林 。 





O00@ « 上 © 3 localhost 站 由 


3% Spring Boot Admin 








图 17.2 没有 任何 实例 在 运行 


我 们 可 以 看 到 ，Spring Boot Admin 泽 示 有 和 零 个 应 用 的 零 个 实例 正在 
运行 。 数 字 下 面 有 “No applications registered.” 这 样 的 提示 信息 ， 说 明 此 
时 这 些 数 字 没 有 任何 意义 。 要 让 Admin 服 务 占 真正 发 挥 作用 ， 我 们 需要 
为 其 注册 应 用 。 


17.1.2 ”注册 Admin 客 户 端 


为 Admin 服 务 器 独立 于 要 展现 Actuator 数据 的 其 他 Spring BootJ 
用 ， 所 以 必须 让 Admin 服 务 颖 能 够 以 某 种 方式 感知 这 些 应 用 。Admin 服 
务 器 注册 Spring Boot Admin 客 户 病 有 两 种 方式 : 


。 每 个 应 用 显 式 向 Admin 服 务 器 注册 自身 ; 
e。 Admin 通 过 Eureka 服 务 注册 中 心 发 现 服 务 。 


接 下 来 ， 我 们 分 别 看 一 下 这 两 种 方案 ， 首 先是 如 何 将 单个 Spring 
Boot 心 用 配置 为 Spring Boot Admin 客 户 端 ， 这 样 它 们 惑 能 同 Admin 服 务 
俐 注册 目 吴 了 。 


显 式 配 置 Admin 客 户 问 应 用 


为 了 让 Spring Boot 应 用 注册 为 Admin 服 务 器 的 客户 端 ， 我 们 必须 将 
Spring Boot Admin client starter 洪 加 到 项 目的 构建 文件 中 。 在 Initializr 
中 ， 我 们 可 以 选中 标签 为 Spring Boot Admin (Clienb 的 复 选 枉 ， 这 样 很 
容易 驶 能 将 这 个 依赖 添加 到 构建 文件 中 。 对 于 Maven 构 建 的 Spring Boot 
应 用 ， 我 们 也 可 以 设置 如 下 的 依赖 : 


<dependency> 
<groupId>de.codecentric</grouplId> 


<artifactId>spring-boot-admin-starter-client</artifactId> 
</dependency> 





各 户 山 库 惟 备 驶 络 之 后 ， 我 们 需要 配置 Admin 服 务 器 的 位 置 。 这 样 
的 话 ， 客 户 奖 台 可 以 将 目 身 注册 进去 。 为 了 实现 这 一 点 ， 我 们 可 以 将 
spring.boot.admin.client.url 属 性 设置 为 Admin 服 务 磊 的 根 路 径 : 


spring: 


application: 
name: ingredient-service 
boot: 
admin: 
client: 
url: http://localhost:90690 





注意 ， 在 这 里 ， 我 们 还 设置 了 spring.application.name 属 性 (在 本 例 
中 ， 了 也 就 是 配料 服务 )。 我 们 之 前 已 经 使 用 这 个 属性 在 Spring Cloud 
Config Server 利 Eureka 中 识别 微服 务 。 这 里 ， 它 的 目的 很 类 似 : 识别 
Admin 服 务 占 中 的 应 用 。 我 们 重 局 应 用 之 后 ， 将 会 看 到 它 出 现在 Admin 
服务 颖 中 ， 如 图 17.3 所 示 。 


和 网 和 : 门 I 让 localhost © 


3% Spring Boot Admin Applications 





LICATIONS NSTANCES STATUS 
1 1 all up 


INGREDIENT-SERVICE 
es: 0.0.17-SNAPSHOT 


图 17.3 Spring Boot Admin UI 展现 了 一 个 已 注册 的 应 用 


尽管 在 图 17.3 中 并 没有 太 多 关于 配料 服务 的 信息 ， 但 是 我 们 可 以 看 
到 应 用 的 启动 时 间 。 如 果 Spring Boot Maven 持 件 配置 了 build-info 
goal 〈 如 16.3.1 小 节 所 讨论 的 那样 ) ， 这 里 还 会 显示 构建 版 本 。 请 放 


心 ， 在 Admin 服 务 如 中 后 击 应 用 之 后 ， 我 们 会 看 到 很 多 其 他 运行 时 的 细 
节 。 我 们 将 会 在 17.2 节 深入 J 了解 Admin 服 务 右 都 提供 了 哪些 功能 。 


我 们 需要 在 所 有 的 应 用 间 午 复 设 置 这 些 在 Admin 服 务 右 中 注册 配料 
服务 的 配置 。 一 种 比较 人 简 捍 的 方式 是 我 们 只 配置 spring.application.name 
属性 ，Spring Cloud Config Server 会 将 spring.boot.admin.dlient.url 发 送 给 
它 的 所 有 客户 端 。 如 果 你 已 经 使 用 Eureka 作 为 服务 注册 中 心 ， 那 么 更 好 
的 方式 是 让 Admin 目 己 去 上 友 现 服务 。 接 下 来 ， 我 们 看 一 下 如 何 将 Admin 
配置 为 Eureka 客 户 端 。 


发 现 Admin 安 户 端 


如 末 想 让 Admin 服 务 器 来 友 现 服务 ， 唯 一 需要 做 的 事情 束 是 砍 加 
Spring Cloud Netflix Eureka Client starter 到 Admin 服 务 亏 的 构建 文件 中 。 
如 下 是 我 们 需要 的 Maven <dependency>: 

<dependency> 
<groupId>org.springframework.cloud</groupId> 


<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId> 
</dependency> 


注意 : 我 们 也 可 以 通过 在 Spring Initializr 中 选择 Eureka 
Discovery 复 选 框 来 瀛 加 该 依赖 。 





Admin 服 务 器 月 用 了 Eureka 客 户 山 功能 之 后 ， 什 么 事情 都 不 需要 做 
了 。 我 们 可 以 直接 略 过 上 文 所 述 的 客户 闫 配置 ， 因 为 Admin 会 目 动 发 现 


注册 在 Eureka 中 的 服务 并 展现 它们 的 Actuator 数 据 。 如 果 Eureka 中 注册 了 
多 个 Taco Cloud 服 务 ， 那 么 它们 将 会 展现 在 Admin 服 务 器 中 (参见 图 
17.4) 。 


O00@ «< 昌 自 Ea localhost # © LU i 


3 Spring Boot Admin Applications 


APPLICATIONS INSTANCES STATUS 


INGREDIENT-SERVICE 
J ps \ ' 0.0.17-SNAPSHOT 


ORDER-SERVICE 
Ee 0.0.17-SNAPSHOT 


TACO-SERVICE 
ww 0.0.17-SNAPSHOT 


ee 0.0.17-SNAPSHOT 


图 17.4 Spring Boot Admin UI 能 够 展现 在 Eureka 中 肥 现 的 所 有 服务 


在 图 17.4 中 列 出 了 4 个 不 同 的 应 用 ， 对 应 了 6 个 服务 : 订单 服务 有 两 
个 实例 ，taco 服 务 有 两 个 实例 ， 其 他 的 两 个 应 用 各 有 一 个 实例 。 这 里 显 
示 的 所 有 应 用 均 处 于 UP 状态 。 如 果 有 应 用 挥 线 〈( 比 如 用 户 服 务 )， 环 
将 会 在 Admin 服 务 右 中 单独 显示 〈 见 图 17.5) 。 


OO@ : 加 © Ca localhost 3 © 山 D 





3 Spring Boot Admin Application@ 


APPLICATIONS NSTANCES NSTANCES DOWN 


4 6 1 


© INGREDIENT-SERVICE ; 
tt ” 0.0.17-SNAPSHOT 


ORDER-SERVICE 
0.0.17-SNAPSHOT 


ww TACO-SERVICE 
0.0.17-SNAPSHOT 


USER-SERVICE 
> E 0.0.17-SNAPSHOT 


图 17.5 ”Spring Boot Admin UI 单独 展现 挥 线 的 服务 ， 与 在 线 的 服务 隔离 开 


作为 Eureka 的 各 户 闪 ，Admin 服 务 右 也 会 将 目 且 注册 为 Eureka 中 的 
服务 。 如 采 要 避免 这 种 现象 ， 我 们 可 以 将 eureka.client.register-with- 
eureka 属 性 设置 为 false: 


eureka: 


client: 
register-with-eureka: false 





与 其 他 的 Eureka 客 户 问 类 似 ， 如 果 不 是 监听 默认 主机 和 问 口 ， 我 们 
束 可 以 配置 Eureka 服 务 右 的 位 置 。 如 下 的 YAML 文 件 将 Eureka 位 置 配 置 
成 eurekal.tacocloud.com 主 机 .: 


eureka: 
client: 


service-url: 
defaultZone: http://eurekal.tacocloud.com:8761/eureka/ 





现在 ， 我 们 已 经 将 多 个 Taco Cloud 服 务 注 册 到 了 Admin 服 务 嚣 中。 
接 下 来 ， 我 们 看 一 下 Admin 服 务 器 都 提供 了 哪些 功能 。 


17.2 ”探索 Admin 服 务 器 


在 将 所 有 的 Spring Boot 应 用 注册 为 Admin 服 务 右 的 客户 六 之 后 ， 我 
们 束 可 以 使 用 Admin 服 务 右 得 到 运行 中 应 用 的 大 量 信息 ， 包 括 : 


。 通用 的 健康 信息 ; 

通过 Micrometer 利 “/metrics” 奖 点 发 布 的 所 有 指标 ; 
环境 属性 ; 

包 和 类 的 日 志 级 别 ; 

线程 跟踪 细 市 ; 

HTTP 请 求 的 跟踪 情况 ; 

审计 日 志 。 


实际 上 ， 几 乎 Actuator 和 又 露 的 所 有 欠 容 我 们 都 可 以 通过 Admin 服 务 
项 来 否 看 ， 只 不 过 它 的 展现 形式 更 加 人 性 化 。 它 包括 了 图 表 和 销 取 信息 
的 过 滤 右 。Admin 服 务 所 展现 的 信息 要 比 本 草 中 看 到 的 多 得 多 ， 限 于 篇 
蛋 ， 我 们 使 用 本 和 剩余 的 内 容 痢 重 介 绍 一 些 Admin 服 务 器 的 完 点 功能 。 


17.2.1 奏 看 应 用 基本 的 健康 状况 和 信息 


正如 我 们 在 16.2.1 小 和 所 提 到 的 那样 ，Actuator 会 通 


过 “health” 和 “info” 闪 点 提供 应 用 的 健康 状况 和 基本 信息 。Admin 服 务 喜 
在 Details 选 项 卡 下 展现 了 这 些 信息 ， 如 图 17.6 所 示 。 


O00@ 《 加 om localhost © oO ho nm 


% Spring Boot Admin 


INGREDIENT-SERVICE Ne JDarkSide lo i 


http://DarkSide.|lo 
Instance 3be305bc734f (of 1) http://DarkSide.k 





Info Health 
git commit: Instance UP 
time: '2018-06-02T18:10:58Z' 
id: b5c104d mongo UP 
branch: master i 322 
build Version: 0.0.17-SNAPSHOT 
artifact: ingredient-service hystrix UP 
name: ingredient-service 
group: tacocloud diskSpace UP 
time: '2018-06-02T18:;11:23,515Z' 
total 500 GB 
free 174 GB 
Metadata threshold 10.5 MB 
jmx.port '58589' configServer UP 
management.port '8081' propertySources [{["configClient” 


“http://github.com/habuma/myapp- 
config/application.yml (document #0)" ] 


图 17.6 ”Spring Boot Admin UI 的 Details 选 项 卡 展现 了 应 用 的 健康 状况 和 基本 信息 


滑 过 Details 选 项 卡 的 Health 和 Info 部 分 ， 我 们 会 在 下 方 看 到 一 些 来 自 
应 用 JVM 的 统计 信息 ， 包 括 展 现 处 理 器 、 线 程 和 内 存 使 用 的 图 表 ， 如 图 
17.7 所 示 。 


O00@ 《 加 3 localhost © [#) 由 口 


包 人 Spring Boot Admin 


INGREDIENT-SERVICE SS 
3be305bc734f (of 1) Details 





Audit Log Heapdump 


Process Threads 
PID UPTIME .LOAD I Y W 上 L 
49809 0d 0h 44m 43s 8 3.84 57 44 64 

上 


Garbage Collection Pauses 





JUN TOTAL TIME SPENT MAX TIME SPENT 
10 0.278s 0.004s 14;40:15 14;40:30 14;40:45 14;41:00 14;41:15 
Memory: Heap Memory: Non heap 
加 时 METASPACE EE 二 SIZE MAX 
56.6 MB 82.9 MB 88.2 MB 1.33 GB 





图 17.7 ”在 Details 选 项 卡 中 下 方 将 会 看 到 额外 的 JVM 内 部 信息 《包括 处 理 茵 、 线 程 和 内 存 统计 数 
据 ) 


图 表 中 所 展现 的 信息 再 加 上 Processes、Garbage Collection Pauses 下 
面 的 指标 ， 可 以 提供 关于 应 用 如 何 使 用 JVM 资 源 的 有 用 信息 。 
17.2.2 ”观察 核心 指标 


在 Actuator 的 所 有 端点 中 ，“%metrics” 冰 点 所 提供 的 信息 可 能 最 不 易 
于 人 类 阅 计 了 。 借 助 Admin 服 务 器 Metrics 选 项 卡 下 的 UI 界面 ， 我 们 可 以 
很 容易 地 消费 应 用 所 生成 的 指标 数据 。 


在 开始 的 时 候 ，Metrics 选 项 卡 并 不 会 展示 任何 指标 。 借 助 页 面 项 部 


的 表单 ， 我 们 能 够 设置 力 要 奉 看 的 一 个 或 多 个 指标 。 


在 图 17.8 中 ， 我 们 监视 了 http.server.requests 分 类 的 两 个 指标 : 第 一 
个 报告 展现 了 发 往 %ingredients” 冰 点 的 HITP GET 请 求 ， 并 且 要 求 返 回 
状态 为 200 (OK); 第 二 个 报告 展现 了 所 有 产生 HTTP 404 (NOT FOUND) 
吧 应 的 请 求 。 


O00 « 加 om localhost © oo ms 


© Spring Boot Admin 


INGREDIENT-SERVICE http /DarkSide.local:8081/ 


http://DarkSide.local:8081/actuator 
Instance 3be305bc734f (of 1) http://DarkSide.local:8081/actuator/health 





Environment LOggers Threads Http Traces Audit Log Heapdump 


http.server.requests v 


exception - vy 
method _ > 
uri _ v 


status A404 vw 


Add Metric 


http.server.requests COUNT S TOTAL_TIME - v MAX v 


exception:none 
method:GET 


. 3428 9.034839572 0.004334177 府 
uri:/ingredients 
status:200 
status:404 39 0.357279409 0.009219171 府 


图 17.8 在 Metrics 选 项 卡 下 ， 我 们 可 以 监视 应 用 的 “metrics” 端 点 发 布 的 所 有 指标 


天 于 这 些 指 标 ， 非 常 棱 的 一 点 在 于 (其 实 几 乎 适用 于 Admin 服 务 器 
展现 的 所 有 内 容 ) ， 这 里 所 展示 的 是 实时 数据 ， 会 目 动 更 新 ， 无 顷 刷新 
页 面 。 


17.2.3 ”探查 环境 属性 


Actuator 的 “env” 端 点 能 够 返回 Spring Boot 应 用 所 有 可 用 的 环 卉 变 
量 ， 这 些 环 境 变 量 来 源 于 各 种 属性 源 。 尺 管 API 妆 点 的 JSON 格 式 啊 应 并 
不 难 读 ， 但 是 Admin 服 务 器 在 Environment 选 项 卡 下 以 更 美观 的 形式 进行 
村 展现 〈 见 图 17.9) 。 


OO0@ 〈 加 Q 


3 Spring Boot Admin 


http://DarkSide.local:8081/ 


INGREDIENT-SERVICE http://DarkSide.local:8081/actuator 


http://DarkSide.local:8081/actuator/health 


Instance 3be305bc734f (of 1) 





Detalls Metrics Loggers Threads Http Traces Audit Log Heapdump 


Environment Manager 








Refresh Context Reset 
spring | @ 
systemProperties 
spring.beaninfo.ignore true 
spring.liveBeansView.mbeanDomain 
true 


spring.application.admin.enabled 


applicationConfig: [classpath:/application.yml] 


spring.application.name ingredientservice 
springCloudClientHostinfo 
spring.cloud.client.hostname DarkSide.local 
127.0.0.1 


spring.cloud.client.ip-address 


图 17.9” Environment 选项 卡 展现 了 环境 属性 ， 并 且 包 全 了 重 写 和 过 滤 值 的 选项 


因为 这 里 可 能 会 有 数 白 个 属性 ， 所 以 可 以 使 用 属性 名 或 值 对 可 用 属 
性 进行 过 滤 。 图 17.9 展 现 了 根据 属性 名 和 /或 值 包 仿 “spring.” 进 行 过 小 后 
的 属性 列表 。 通 过 页 面 项 部 的 Environment Manager 表 单 ，Admin 服 务 喜 
还 允许 我 们 议 置 或 重 写 环境 属性 。 


17.2.4 查看 和 设置 日 志 级 别 


Actuator 的 “loggers” 痪 点 对 于 理解 或 重 与 运行 中 应 用 的 日 志 级 别 非 
第 有 用 。Admin 服 务 器 的 Loggers 选 项 卡 基于 “/loggers” 病 点 提供 了 一 个 非 
第 易于 使 用 的 UI 页 面 ， 进 一 步 简化 了 应 用 中 的 日 志和 管理。 几 17.10 展 现 
了 根据 org.springframework.boot 名 称 过 滤 后 的 ljoggers。 


O00@ < 四 有 目 吕 localhost © © 由 器 


© Spring Boot Admin 


一 http://DarkSide.local:8081/ 
INGR E DI ENT SE RVICE http://DarkSide.local:8081/actuator 


Instance 3be305bc734f (of 1) http://DarkSide.local:8081/actuator/health 





Details Metrics Environment oggers Http Traces Audit Log Heapdump 


| org.springframework.boot @ | 152/699 
class only TT configured 
org.springframework.boot OFF ERROR WARN INFO DEBUG TRACE € Reset 
org.springframework.boot.BeanDefinitionLoader OFF ERROR WARN INFO DEBUG “TRACE Reset 
org.springframework.boot.BeanDefinitionLoader$ClassExcludeFilter OFF ERROR WARN NFO DEBUG “TRACE Reset 
org.springframework.boot.DefaultApplicationArguments OFF ERROR WARN INFO DEBUG “TRACE Reset 
org.springframework.boot.DefaultApplicationArguments$ Source OFF ERROR WARN INFO DEBUG TRACE Reset 
org.springframework.boot.SpringApplication OFF ERROR WARN INFO DEBUG “TRACE Reset 


图 17.10 ”Loggers 选 项 卡 会 展示 应 用 中 包 和 类 的 日 志 级 列 ， 并 且 允 许 我 们 重 写 它们 的 级 别 


路 认 情 况 下 ，Admin 服 务 需 会 展现 上 所 有 包 和 类 的 日 in 它们 可 
以 通过 名 称 《〈 仅 限于 类 ) WA J JX 
不 支持 对 由 根 logger 继 承 来 的 级 别 进行 过 滤 。 


17.2.5 ”监控 线程 


在 应 用 多 个 线程 可 以 并 行 运 行 。 尽 管 %threaddump” 疹 点 《在 
16.2.3 小 市 进行 过 摘 述 ) 提供 了 应 用 运行 中 线程 状态 的 快照 ， 但 是 Spring 
Boot Admin 的 Threads 选 项 卡 能 够 实时 查看 应 用 中 所 有 的 线程 ( 见 
图 17.11) 。 


SO@@ < 加 [9 3 localhost 


% Spring Boot Admin 


http://DarkSide.local:8081 


INGREDIENT-SERVICE http /DarkSide local:8081/actuator 


http://DarkSide.local:8081/actuatorhealth 


Instance 3be305bc734f (of 1) 


Detalls Metncs ll Loggers Weads Http Traces Audit Log Heapdump 





1 I 1 I I IE 1 1 1 1 1 | I 1 
Name 14:23:10 14:23:15 14:23:20 14:;23:25 14:23:30 14;23:35 14:23:40 14:23:;45 14:;23:50 14:23:55 14:24:00 14;24:05 14:24:10 14;24:15 14:24;20 14:24 


waereetorder 
园 Finatizer = 二 = 二 = -=< 人 < 

Thread ld 3 

Thread name Finalizer 

Thread state WAITING 

Blocked count 54 

Blocked time -1 

Waited count 18 

Waited time -1 

Lock name java.lang.ref.ReferenceQueue$Lock@7fed7465 

Lock owner id -1 


Lock owner name 


Stacktrace 


java.lang.Object.wait(Object.java:—-2) 
java.lang.ref.ReferenceQueue.remove(ReferenceQueue. -java:143) 
java.lang.ref.ReferenceQueue.remove(ReferenceQueue. java:164) 
java.lang.ref.FinalizerS$FinalizerThread.run(Finalizer.java:209) 


EY sionet Dispatener ”IE 
Ee Tee sccepeo ”IE 
ERMI TCP Accept-58589 ODDS 站 


图 17.11 ”我们 可 以 使 用 Admin UI 的 Threads 选 项 卡 实 时 监控 应 用 的 线程 


“/threaddump” 问 点 只 是 捕获 菜 个 时 刻 的 快照 ，Threads 选 项 卡 中 的 条 
形 图 与 之 不 同 ， 它 是 持续 更 新 的 ， 展 示 每 个 线程 的 状态 : 线程 可 运行 的 
话 ， 是 绿色 的 ; 等 竺 的 话 ， 是 贡 色 的 ; 阻 瑟 的 话 ， 是 红色 的 。 


要 全 看 休 个 线程 的 细 市 信息 ， 可 以 反击 列表 中 的 线程 行 。 这 样 会 完 
示 该 线程 的 历史 数据 ， 包 丘 线 程 当前 的 堆栈 。 


17.2.6 ”跟踪 HTTP 请 求 


Spring Boot Admin UI 的 Http Traces 选 项 卡 《〈 见 图 17.12) 展现 了 
Actuator“/httptrace” 病 点 的 数据 。 与 “/httptrace” 并 点 返回 请 求 时 最 近 的 
100 个 请 求 不 同 ，Http Traces 选 项 卡 列 出 了 完整 的 HTTP 请 求 历史 。 而 
上 且 ， 在 我 们 打开 这 个 选项 卡 的 时 候 ， 数 据 会 一 直 刷 新 。 如 果 你 离开 这 个 
选项 卡 再 回来 ， 那 么 它 初始 会 显示 100 条 最 近 的 请 求 ， 但 是 会 从 当前 时 
刻 开 始 进行 跟 踩 。 


我 们 可 以 看 到 ，Http Traces 选 项 卡 包含 了 一 个 随时 间 变 化 的 HTTP 尝 
量 的 堆积 图 (stacked graph) 。 这 个 图 使 用 不 同 的 颜色 来 表示 成 功 和 失 
败 的 请 求 : 绿色 代表 成 功 ， 黄 色 代 表 客 户 姗 铺 误 《例如 404 级 别 的 HITP 
响应 ) ， 红 色 代 表 服 务 器 错误 〈 如 500 级 别 的 HITP 响 应 ) 。 如 果 将 鼠标 
指针 移动 到 图 上 ， 束 会 弹出 一 个 巧 停 框 〈 如 图 17.12 最 右 侧 所 示 ) ， 显 
示 给 定时 间 分 解 的 请 求 计数 。 


O00 《 口 Q 


§ 
CQ 
[ee 
DB 
口 
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INGREDIENT-SERVICE Mi soey 


1/actUator 


Instance 4274e9bb8923 (of 1) http://10.0.0.94:8081/actuator/health 


Detalls Metnmcs Environment | TS Threads Audit Log Heapdump 





99/100 
success @ client errors @ server errors @ exclude /actuator/** 





16:02-33 16:02:33 16:02:34 16:02-34 16:02:35 16:02;35 16:02:36 16:02-36 16:02:3; 
Timestamp Method Path Status Content-Type Length Time 
二 os 6 GET http://localhost:8081/ingredients ED application/json 3ms 
de 2 2 2 GET http://localhost:8081/ingredients ED application/json 3ms 
ee ba GET http://localhost:8081/bogus/path 404 application/json 32 ms 
pn pis 号 3 GET http://localhost:8081/ingredients ED application/json 3ms 


图 17.12 ”Http Traces 选 项 卡 会 跟 踩 该 应 用 最 近 的 HITP 流 量 ， 包 括 产 生 错 误 的 请 求 信 息 


在 堆积 图 的 下 方 展现 了 跟 躁 历史 ， 应 用 接收 a 到 的 每 个 请 求 部 会 对 应 
一 行 。 扩 击 其 中 一 行 ， 束 会 展开 显示 该 请 求 的 额外 数据 ， 包 括 请 求 和 啊 
应 的 头 信息 《〈 见 图 17.13) 。 


rmuitithreading - ls there a o “* [1 Spring Boot Admin Referenc * 和夫 Spring Boot Admin 


< Sl © localhost:9090/#/instances/4274e9bb8923/httptrace 


% Spring Boot Admin 
INGREDIENT-SERVICE 





4274e9bb8923 (of 1) Details Metnics Environment Loggers Threads Http Trace Audit Log Heapdump 
06/02/2018 http://localhost:8081/ingredi 
ey GET pi/ /ng application/json 2 ms 
16:07:57.479 ents 


{ 
"Principal”: null, 
"session"”: null, 
"request": 1{ 
"method": "GET", 
"uri":s "http://localhost:8081/ingredients", 
"headers": 1{ 
“Bost 3 [ 
"localhost:8081" 
]， 
"User-Agent": [ 
"Curl/7.54.0" 
]， 
“ARACCept 3 [ 
mm 
] 
}， 
"remoteAddress": null 
}， 
"response": 1{ 
"status": 200, 
"headers": 1{ 
"Content-Type”": [ 
"application/json;charset=UTF-8" 
] 
} 
}, 
"timeTaken”": 2, 
"timestamp": "2018-06-02T22:07:57.4792" 
} 


图 17.13 ”点击 Http Traces 选 项 卡 中 的 请 求 条 目 ， 将 会 展现 该 请 求 额外 的 详情 
17.3 ”保护 Admin 服 务 器 


正如 我 们 在 第 16 和 章 所 讨论 的 那样 ，Actuator 交 点 对 外 骏 露 的 信息 并 
不 能 随便 消费 。 写 们 包含 的 信息 骏 露 了 应 用 的 详情 ， 这 些 信息 只 有 应 用 
程序 的 管理 员 才 能 答 看 。 另 外 ， 还 有 一 些 姗 点 允许 对 应 用 进行 变更 ， 它 
们 束 更 个 应 该 对 所 有 人 开放 了 。 


正如 安全 性 对 于 Actuator 来 说 非常 重要 一 样 ， 它 对 Admin 服 务 喜 同 


样 重要 。 除 此 之 外 ， 如 果 Actuator 端 点 需要 认证 ， 那 么 Admin 需 要 知道 
凭证 信息 才能 访问 这 些 端 点 。 接 下 来 ， 我 们 看 一 下 如 何 为 Admin 服 务 需 
添加 一 些 安 全 性 。 痛 先 ， 从 认证 开始 。 


17.3.1 为 Admin 服 务 器 启用 登录 功能 


驮 认 情 况 下 ，Admin 服 务 亏 是 不 安全 的 ， 所 以 为 其 添加 安全 性 功能 
是 一 种 好 的 做 法 。 因 为 Admin 服 务 右 束 是 一 个 Spring Boot 必 用， 上 所 以 我 
们 可 以 使 用 Spring Security 来 保护 它 。 这 一 点 与 其 他 的 Spring Boot 心 用 完 
全 类 似 。 束 保 使 用 Spring Security 剑 护 其 他 的 应 用 一 样 ， 我 们 可 以 自由 
选择 最 适合 需求 的 安全 模式 。 


按照 最 小 的 要 求 ， 我 们 需要 江 加 Spring Boot security starter 到 Admin 
服务 器 的 构建 文件 中 ， 既 可 以 在 mitializr 中 选中 Security 复 选 枉 ， 也 可 以 
洪 加 如 下 的 <dependency> 到 项 目的 pom.xml 文 件 中 : 


<dependency> 
<grouplId>org.springframework.boot</groupId> 


<artifactId>spring-boot-starter-security</artifactId> 
</dependency> 





然后 ， 为 了 避免 观察 Admin 服 务 右 的 日 志 才 能 获取 随机 生成 的 密 
人 码 ， 我 们 可 以 将 简单 的 官 理 员 用 户 名 和 密码 配置 在 application.yml 中 : 


spring: 
security: 


User: 
name: admin 
password: 53cr3t 





现在 ， 当 在 浏览 硕 中 加 载 Admin 服 务 硕 的 时 候 ， 我 们 会 看 到 Spring 
Security 默 认 的 登录 表单 ， 提 示 我 们 输入 用 户 名 和 黎 码 。 按 照 这 里 的 配 
置 上 请 段 ， 输 入 “admin” 和 ?53cr3f" 残 可 以 登录 了 了 。 当 然 ， 这 十 一 个 极其 基 
本 的 安全 配置 。 我 推荐 你 参考 第 4 章 了解 配 置 Spring Security 的 各 种 方 
式 ， 为 Admin 服 务 如 提供 更 丰富 的 安全 模式 。 


17.3.2” 为 Actuator 司 用 认证 


在 16.4 和 中， 我 们 讨论 了 如 何 使 用 HTTP Basic 认 证 保护 Actuator 病 
点 。 按 照 这 种 方式 ， 我 们 会 将 不 知道 Actuator 端 点 用 户 名 和 密码 的 用 户 
拒 之 门 外 。 也 丈量 味 看 Admin 服 务 硕 不 能 消费 Actuator 冰 点 了 ， 除 非 提 
供用 户 名 和 密码 。 但 是 ，Admin 如 何 得 到 凭证 信息 呢 ? 


Admin 服 务 器 的 客户 端 应 用 可 以 通过 直接 同 Admin 服 务 器 注册 上 自 刁 
或 被 Eureka 发 现 的 方式 提供 凭证 信息 给 Admin 服 务 器 。 如 果 应 用 是 直接 
可 Admin 服 务 器 注册 自身 ， 那 么 可 以 在 注册 时 发 送 任 证 信息 。 我 们 需要 
配置 几 个 属性 启用 该 功能 。 


spring.boot.admin.client.instance.metadata.User.name 和 
spring.boot.admin.client.instance. metadata.user.password 属 性 指定 了 Admin 
服务 器 访问 应 用 的 Actuator 闹 点 时 可 以 使 用 的 和 凭证 信息 。application.yml 
中 如 下 的 代码 厂 段 展 示 了 如 何 设置 这 些 属 性 : 





spring: 
boot: 
admin: 
client: 


url: http://localhost:90690 
instance: 
metadata: 
user.name: ${spring.security.user.name} 
user.password: ${spring.security.user.password} 





用 户 名 和 密码 必须 要 设置 在 所 有 癌 Admin 服 务 器 注册 的 应 用 中 。 这 
里 给 定 的 值 必须 要 匹配 Actuator 端 点 HITP Basic 认 证 头 信息 所 需 的 用 户 
名 和 黎 但 。 在 本 例 中 ， 它 们 设置 成 了 admin 和 password， 也 殊 是 访问 
Actuator 闹 点 所 配置 的 任 证 信息 。 


如 果 应 用 是 由 Admin 服 务 右 退 过 Eureka 发 现 的 ， 那 么 我 们 需要 设置 
eureka.instance.metadata-map.user.name 和 eureka.instance.metadata- 


map.user.password: 


eureka: 
instance: 


metadata-map: 
user .name: admin 
user.password: password 





当 应 用 使 用 Eureka 注 册 的 时 候 ， 和 凭证 信息 将 会 包含 到 Eureka 注 册 记 
录 的 元 数据 中 。 当 Admin 服 务 右 发 现 应 用 时 ， 会 和 应 用 的 其 他 详情 一 起 
从 Eureka 获 取 它 的 途 证 信息 。 


17.4 小结 


。 Spring Boot Admin 服 务 器 能 够 消费 一 个 或 多 个 Spring Boot 应 用 的 
Actuator 咒 上 扣 ， 并 在 一 个 用 尸 友 好 的 Web 应 用 中 展现 数据 。 

。 Spring Boot 可 以 问 Admin 服 务 器 注册 目 身 ， 也 可 以 通过 Eureka 被 
Admin 服 务 右 目 动 友 现 。 


e 与 捕获 应 用 状态 快照 的 Actuator 中 点 不 同 ，Admin 服 务 器 可 以 展现 


应 用 内 部 运行 状况 的 实时 视图 。 

。 借助 Admin 服 务 占 能 够 很 容易 地 过 小 Actuator 结 果 ， 在 有 些 场 景 
下 ， 还 可 以 以 可 视 化 图 表 的 形式 展现 数据 。 

。 因为 Admin 服 务 妖 就 是 一 个 Spring Boot 应 用 ， 上 所 以 可 以 使 用 任意 可 


用 的 Spring Security 方 式 来 保护 它 。 


第 18 章 ”使 用 JMX 监 控 Spring 


e。 人 使 用 Actuator 端 点 的 MBean 


。 将 Spring bean 和 地 露 为 MBean 


e。 及 布 通知 





JMX (Java Management Extensions， 的 展 ) 作为 监视 和 和 党 
理 Java 应 用 程序 的 标准 方法 已 经 存在 超过 了 15 年 。 通 过 暴露 名 为 
MBean《〈 托 管 bean) 的 托管 组 件 ， 外 部 的 JMX 各 户 痛 可 以 通过 调用 
MBean 中 的 操作 、 探 否 属 性 和 监视 事件 来 管理 应 用 程序 。 


在 Spring Boot 应 用 中 ，JMX 会 动 司 用 。 这 样 的 话 ，Actuator 的 所 
有 奖 点 均 会 对 露 为 MBean。 另 外 ， 写 还 会 挫 建 一 个 很 便利 的 环境 ， 能 够 
很 容易 地 将 Spring 应 用 上 下 文中 的 bean 暴 露 为 MBean。 作 为 探索 Spring 和 
JMX 功 能 的 开始 ， 我 们 首先 看 一 下 Actuator 端 点 是 如 何 暴露 为 MBean 
的 。 


18.1 使 用 Actuator MBean 


我 们 可 以 回头 看 一 下 表 16.1， 除 了 “heapdump” 之 外 ， 这 里 列 出 的 
所 有 交点 均 骏 露 成 MBean。 我 们 可 以 使 用 任意 的 JMX 客 户 站 连接 
Actuator 疹 点 MBean。 售 助 Java 开 发 工具 集中 的 JConsole， 我 们 可 以 看 到 
Actuator MBean 列 天 了 org.springframework.boot 域 下 ， 如 图 18.1 所 示 。 





SG Java Monitoring & Management Console 
Connection Window Help 四 
@ pid: 17247 tacocloud.gateway.SimpleActuatorApplication 
Overview Memory Threads Classes VM Summary sr 





p "DefaultDomain 
p “jjMImplementation 
> Tomcat 
Pp com.Sun.management 
> NN java.lang 
p java.nio 
pb “java.util.logging 
™ SN org.springframework.boot 

> Admin 

™ a 

>» Archaius 
哇 Auditevents 
时 Beans 
名 Conditions 
二 Configprops 
久 Env 
哆 Features 
9 Health Actuator 庙 点 
哆 Httptrace MBeans 
字 Info 
号 Loggers 
号 Mappings 
嘲 Metrics 
号 Refresh 
哺 Scheduledtasks 
> 名 Threaddump 

pb org.springframework.cloud.conte 


vy yy 


pb org.springframework.cloud.conte 





pb “WW org.springframework.cloud.conte 


图 18.1 Actuator 端 点 会 自动 暴露 为 JMX MBean 


Actuator MBean 闹 点 非常 好 的 一 点 在 于 它们 默认 就 是 对 外 烘 露 的 。 
我 们 没有 必要 明确 声明 要 包含 哪些 MBean 闹 点， 但 是 对 于 HTTP 绒 点 ， 


我 们 是 需要 这 样 做 的 。 我 们 可 以 通过 设置 
management.endpoints.jmx.exzposure.include 和 management.endpoints.jmX. 
exposure.exclude 必 性 来 缩小 可 选 的 范围 。 人 例如， 我 们 想 要 限制 Actuator 
疹 点 只 骏 露 “health”%info”“bean2” 和 “conditions” 奖 点， 那么 可 以 按照 如 


下 的 方式 设置 management.endpoints.jmx.exposure.include: 


management: 
endpoints: 


]Jmx : 
exposure: 
include: health,info,bean,conditions 





我 们 只 想 排除 其 中 的 几 个 路 操 的 话 ， 可 以 控 照 如 下 的 方式 设置 


management.endpoints. jmx.exposure.exclude 属 性 : 


management: 
endpoints: 


]Jmx : 
exposure: 
exclude: env,metrics 





在 这 里 ， 我 们 使 用 management.endpoints.jmx.exposure.exclude 排 除 
了 “Venv” 和 “/metrics” 病 点 。 所 有 其 他 的 Actuator 闹 点 依然 会 梭 器 为 
MBean 。 


要 在 JConsole 中 调用 一 个 或 多 个 Actuator MBean 上 所 托管 的 操作 ， 可 
以 在 左 侧 树 中 展开 MBean 闹 点 ， 然 后 在 Operations 下 选择 所 需 的 操作 。 


例如 ， 你 想 要 探查 tacos.ingredients 包 的 日 志 级 别 ， 那 么 可 以 展开 
Loggers MBean 并 点 击 名 为 loggerLevels 的 操作 ， 如 图 18.2 所 示 。 在 右上 
方 的 表单 中 ， 在 name 文 本 域 中 输入 包 名 (tacos.ingredients) ， 然 后 点 击 


loggerLevels 按 钮 。 
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图 18.2 ”使 用 JConsole 展 现 Spring Boot 应 用 的 日 志 级 别 


在 点 击 loggerLevels 按 钮 之 后 ， 将 会 弹出 一 个 对 话 框 ， 展 现 来 
目 “/loggers” 病 点 MBean 的 啊 应 ， 大 人 至 如 图 18.3 所 示 。 


[3 Operation return value 





¢ configuredLevel=null 
< 一 > 
| effectiveLeveL=INF0 


图 18.3 ”在 JConsole 中 ，“loggers” 端 点 MBean 所 展现 的 日 志 级 别 


尽管 JConsole UI 的 使 用 方式 有 些 案 抄 ， 但 是 你 应 该 可 以 掌握 它 的 技 
巧 并 使 用 相同 的 方式 来 探索 其 他 的 Actuator 闪 点 。 


如 有 末 你 不 喜欢 JConsole， 也 没有 问题 ， 有 很 多 其 他 的 JMX 客 户 闪 可 
供 选 择 。 


18.2 ”创建 目 己 的 MBean 


借助 Spring， 可 以 很 容易 地 将 任意 bean 导 出 为 JMX MBean。 我 们 唯 
一 需要 做 的 束 古 在 bean 类 上 添加 @ManagedResource 注 解 ， 然 后 在 方法 
或 属性 上 添加 @ManagedOperation 或 @ManagedAttribute。 Spring 会 负责 
剩余 的 事情 。 


例如 ， 我 们 想 要 提供 一 个 MBean， 用 来 跟踪 通过 Taco Cloud 创 建 了 
多 少 个 taco 订 单 ， 那 么 我 们 可 以 定义 一 个 服务 beaan， 在 这 个 服务 中 保持 
己 创 建 taco 的 数量 。 程 序 清 单 18.1 展 现 了 该 服务 。 


程序 清单 18.1 统计 已 创建 taco 订 单数 量 的 MBean 


package tacos.tacos,; 

Import java.util.concurrent.atomic.AtomicLong,; 

import 
org.springframework.data.rest.core.event.AbstractRepositoryEventliste 

ner; 

import org.springframework.JjJmx.export.annotation.ManagedAttribute; 

import org.springframework.Jmx.export.annotation.ManagedOperation; 

import org.springframework.jJmx.export.annotation.ManagedResource.; 

Import org.springframework.stereotype.Service; 


QService 
QManagedResource 
public class TacoCounter 
extends AbstractRepositoryEventListener<Taco> { 


private AtomicLong counter ; 


public TacoCounter(TacoRepository tacoRepo) { 
long initialCount = tacoRepo.count(); 
this.counter = new AtomicLong(initialCount); 


} 


QOverride 
protected void onAfterCreate(Taco entity) { 
counter .incrementAndGet( ) ; 


} 


@QManagedAttribute 
public long getTacoCount() { 
return counter .get() ; 


} 


QManagedOperation 
public long increment(long delta) { 
return counter.addAndGet(delta); 


} 
} 


TacoCounter 类 使 用 了 @Service 注 和解， 所 以 它 将 会 被 组 件 扫描 功能 所 
发 现 并 且 会 注册 一 个 实例 作为 bean 存 放 到 Spring 应 用 上 下 文中 。 它 还 使 
用 了 @ManagedResource 注 解 ， 表 明 这 个 bean 是 一 个 MBean。 作 为 
MBean， 它 又 露 了 一 个 属性 和 一 个 操作 。getTacoCount() 方 法 使 用 了 


@ManagedAttribute 注 解 ， 将 会 替 嚣 为 一 个 MBean 属 性 ;而 increment() 方 
法 使 用 了 @ManagedOperation 注 解 ， 将 会 暴露 为 MBean 操 作 。 


图 18.4 展 现 了 TacoCounter MBean 在 JConsole 中 是 什么 样子 。 
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图 18.4 在 JConsole 中 看 到 的 TacoCounter 的 操作 和 属性 


TacoCounter 还 有 一 个 扩 巧 ， 不 过 这 与 JMX 并 没有 什么 关系 。 这 个 
类 扩展 了 AbstractRepositoryEventListener， 每 当 通 过 TacoRepository 保 存 
Taco 的 时 候 ， 它 都 会 得 到 通知 。 在 本 例 中 ， 在 创建 和 保存 新 Taco 对 象 的 
时 候 ，onAfterCreate0) 方 法 将 会 被 调用 ， 我 们 在 这 里 让 计数 大 增加 1。 
AbstractRepositoryEventListener 还 提供 了 多 个 方法 来 处 理 对 象 创建 、 你 
人 存 和 删除 前 后 的 事件 。 


使 用 MBean 的 操作 和 属性 在 很 大 程度 上 是 一 个 拉 取 操作 。 换 句 话 
说 ， 就 算 MBean 属 性 的 值 发 生 了 变化 ， 除 非 通过 JMX 客 户 疹 奏 看 该 属 


性 ， 人 否则 我 们 也 不 会 知道 。 接 下 来 ， 我 们 换 一 个 话题 ， 看 一 下 如 何 将 
MBean 的 通知 推送 至 JMX 客 户 站 。 


18.3” ”发达 瞬 知 


信 助 Spring 的 NotificationPublisher，MBeans 可 以 推送 通知 到 感 兴趣 
的 JMX 客 户 疹 。NotificationPublisher 有 一 个 sendNotification0) 方 法 ， 当 得 
到 一 个 Notification 对 象 时 ， 它 会 发 送 通知 给 任意 订阅 该 MBean 的 JMX 客 


户 站 。 


要 让 霖 个 MBean 及 送 通知 ， 它 必须 要 实现 
NotificationPublisherAware 接 口 ， 访 接口 要 求实 现 一 个 
setNotificationPublisher() 方 法 。 例 如 ， 我 们 希望 每 创建 100 个 taco 束 发 这 
一 个 通知 。 我 们 可 以 修改 TacoCounter 类 ， 让 它 实现 
NotificationPublisherAware， 并 使 用 注入 的 NotificationPublisher 每 创建 
100 个 taco 时 就 发 送 通 知 。 程 序 清单 18.2 展 现 了 启用 通知 功能 TacoCounter 
所 需要 的 变更 。 


程序 清单 18.2 每 创建 100 个 taco 就 发 送 通 知 





QService 

QManagedResource 

public class TacoCounter 
extends AbstractRepositoryEventListener<Taco> 
ijmplements NotificationpublisherAware { 


private AtomicLong counter ; 
private NotificationPpublisher np; 


QOverride 

public void setNotificationPpublisher(NotificationPpublisher np) { 
this.np = np; 

} 


QManagedOperation 
public long increment(long delta) { 
long before = counter.get(); 
long after = counter.addAndGet(delta); 
if ((after / 166) > (before / 166)) { 
Notification notification = new Notification( 
"taco.count", this, 
before, after + "th taco created!"); 
np.sendNotification(notification); 


} 


return after; 


在 JMX 客 户 关中 ， 我 们 需要 订阅 TacoCounter MBean 来 接收 通知 。 
每 创建 100 个 taco， 客 户 闪 了 束 会 收 到 通知 。 风 18.5 展 现 了 通知 在 JConsole 
中 的 样子 。 
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图 18.5” JConsole 订 阅 了 TacoCounter MBean， 每 创建 100 个 taco 就 会 收 到 通知 


通知 是 应 用 程序 主动 回 监 视 客 性 是 友 太 数 据 和 各 警 的 好 办 法 。 这 样 
做 的 话 ， 束 不 需要 客户 凯 轮 询 托管 属性 或 调用 托 官 操作 了 。 


18.4 小结 


。 大 多 数 Actuator 闹 点 都 可 以 作为 MBean 使 用 ， 可 以 被 JMX 和 客户 闹 消 
省 


费 。 

。 Spring 会 自动 司 用 JMX， 用 来 监控 Spring 应 用 上 下 文中 的 bean。 

e。 Spring bean 可 以 通过 添加 @ManagedResource 注 解 导 出 为 MBean。 通 
过 为 bean 类 添加 @ManagedOperation 和 CQ@ManagedAttribute 注 解 ， 它 
的 方法 和 属性 可 以 导出 为 托管 的 操作 和 属性 。 

。 Spring bean 可 以 使 用 NotificationPublisher 发 送 通知 给 JMX 客 户 端 。 


第 19 草 ”部 者 Spring 


本 草 内 容 : 


。 将 Spring 应 用 构建 为 WAR 或 JAR 文 件 


。 推 达 Spring 应 用 全 Cloud Foundry 


。 使 用 Docker 容 硕 化 Spring 应 用 





想 一 下 你 最 喜欢 的 动作 片 。 现 在 我 们 想象 一 下 ， 你 要 去 电影 院 看 屠 
部 电影 ， 在 高 速 追 逐 、 爆 炸 和 战斗 中 体验 一 场 激动 人 心 的 视听 之 旅 ， 但 
是 电影 最 终 却 在 好 人 打倒 坏人 之 前 破 然 而 止 。 电 影院 的 灯 一 亮 ， 所 有 人 
都 被 带 出 影院 ， 我 们 没有 看 到 电影 里 的 冲突 是 如 何 解决 的 。 虽 然 开 头 很 
精彩 ， 但 是 重要 的 是 影片 的 高 潮 部 分 。 没 有 它 ， 那 就 是 为 了 行动 而 行 
动 。 

现在 想象 一 下 我 们 开发 了 应 用 程序 ， 并 在 解决 业务 问题 方面 投入 了 


大 量 的 精力 和 创造 力 ， 但 是 从 来 没有 将 应 用 程序 部 普 给 其 他 人 使 用 和 至 
受 。 当 然 ， 我 们 编写 的 大 多 数 应 用 程序 午 不 涉及 汽车 退 逐 或 娄 炸 《至 少 


我 不 厦 望 如 此 ) ， 但 是 在 开 有 过程 中 会 有 一 定 的 忙乱 。 并 不 是 我 们 所 与 
的 每 一 行 代 码 和 都 是 为 生产 而 与 的 ， 但 是 ， 如 果 没 有 任何 代码 家 部 普 的 
话 ， 将 是 极 疹 令 人 失望 的 。 


到 目前 为 止 ， 我 们 一 直 在 关注 Spring Boot 所 提供 的 帮助 应 用 开发 的 
特性 。 在 这 个 过 程 中 ， 已 经 有 了 一 些 令 人 兴奋 的 进展 。 如 末 不 越过 终点 
线 ， 也 融 征 部 普 应 用 程序 ， 那 么 这 一 切 都 十 徒 开 的。 


在 本 章 中 ， 我 们 将 会 在 使 用 Spring Boot 开 发 应 用 的 基础 上 再 进 一 
步 ， 看 一 下 如 何 部 普 这 些 应 用 。 尽 管 对 于 部 普 过 基于 Java 应 用 的 人 来 
说 ， 这 些 事情 是 显而易见 的 ， 但 是 Spring Boot 以 及 相关 的 Spring 项 目 有 
一 些 独特 之 处 ， 它 们 使 得 Spring Boot 应 用 的 部 署 与 众 不 同 。 


实际 上 ， 与 大 多 数 以 WAR 文 件 部 普 的 Java Web 应 用 不 同 ，Spring 
Boot 提 供 了 多 种 部 署 方案 。 在 开始 学 习 如 何 部 痢 Spring Boot 悄 用 之 前 ， 
我 们 看 一 下 所 有 的 可 选 方案 并 选择 最 适合 需求 的 几 种 。 


19.1 权衡 各 种 部 鞋 方 采 


我 们 可 以 以 多 种 方式 构建 和 运行 Spring Boot 恬 用。 在 附录 中 将 介绍 
其 中 的 一 部 分 ， 包括 : 


。 使 用 Spring Tool Suite 或 IntelliJ IDEA 在 IDE 中 运行 应 用 : 

。 在 命令 行 中 通过 Maven spring-boot:run goal 或 Gradle bootRun 任 务 运 
行 应 用 ; 

。 使 用 Maven 或 Gradle 生 成 一 个 可 换行 的 JAR 文 件 ， 既 可 以 在 命令 行 


。 使 用 Maven 或 Gradle 生 成 一 个 WAR 文 件 ， 以 部 署 到 传统 的 Java 应 用 
服务 器 中 。 


这 些 可 选 方 案 部 非常 适合 在 开 友 阶段 运行 人 应用。 但是， 如 来 我 们 想 
要 将 应 用 部 垩 到 生产 环境 或 者 其 他 非 开 及 环境 ， 叉 该 怎么 从 呢 ? 


通过 IDE 或 者 Maven、Gradle 运 行 应 用 并 不 适用 于 生产 环境 ， 可 执行 
的 JAR 文 件 或 者 传统 的 WAR 文 件 才 赴 将 应 用 部 闭 到 生产 环境 的 可 行 方 
案 。 既 然 可 以 部 署 为 WAR 文 件 或 JAR 文 件 ， 那 我 们 该 选择 哪 种 呢 ? 通 
前， 这 种 选择 取决 于 要 将 应 用 部 获 到 传统 的 Java 应 用 服务 颖 中 还 是 部 赣 
到 云 中 。 


部 车 到 Java 应 用 服务 器 中 : 如 采 必 须要 将 应 用 部 普 到 Tomcat、 
WebSphere、WebLogic 或 其 他 传统 的 Java 应 用 服务 占 中 ， 其 实 我 们 
列 无 选择 ， 只 能 将 应 用 构建 为 WAR 文 件 。 

部 闭 到 云 中 : 如 末 你 计划 将 应 用 部 赣 到 云 中 ， 不 管 古 Cloud 
Foundry、 Amazon Web Services (AWS) 、Azure、Google Cloud 
Platform 还 是 其 他 云 平 台 ， 那 么 可 执行 的 JAR 文 件 是 最 佳 选择 。 即 
便 云 平台 文 持 WAR 部 普 ，JAR 文 件 格式 也 要 比 WAR 格 式 简 单 得 
多 ，WAR 文 件 是 专门 针对 应 用 服务 器 部 普 设 计 的 。 


在 本 章 中 ， 我 们 将 会 关注 3 种 部 赣 场景 。 


将 Spring Boot 悄 用 以 WAR 文 件 的 形式 部 普 到 Java 应 用 服务 右 中 ， 比 
如 Tomcat。 

。 将 Spring Boot 应 用 作为 可 执行 的 JAR 文 件 ， 推 送 到 Cloud Foundry 

中 。 


。 将 Spring Boot 应 用 打包 到 Docker 容 器 中 ， 将 其 部 署 到 任何 支持 
Docker 形 式 的 平台 中 。 


首先 ， 我 们 看 一 下 如 何 将 配料 服务 应 用 构建 为 一 个 WAR 文 件 ， 这 
样 它 就 可 以 部 署 到 像 Tomcat 这 样 的 应 用 服务 器 中 了 。 


19.2 构建 和 部 团 WAR 文 件 


在 本 书 中 ， 我 们 编写 Taco Cloud 应 用 所 需 的 服务 时 ， 都 是 在 IDE 中 
运行 ， 或 者 通过 命令 行 以 可 执行 文件 的 形式 运行 。 不 管 是 使 用 哪 种 方 
式 ， 都 会 有 一 个 验 入 式 的 Tomcat 服 务 左 〈 在 Spring WebFlux 应 用 中 会 是 
Netty) 来 为 应 用 的 请 求 提供 服务 。 


在 很 大 程度 上 ， 借 助 Spring Boot 的 目 动 配置 ， 我 们 不 需要 创建 
web.xml 文 件 或 Servlet initializer 类 来 声明 Spring 的 DispatcherServlet， 以 
实现 Spring MVC 相 关 的 功能 。 如 果 要 将 应 用 程序 部 普 到 Java 心 用 服务 霹 
中 ， 就 需要 构建 一 个 WAR 文 件 。 而 且 ， 为 了 让 应 用 服务 右 知 道 如 何 运 
行 应 用 程序 ， 我 们 还 需要 在 WAR 文 件 中 包 侣 一 个 servlet initializer， 以 扮 
沉 web.xml 文 件 的 角色 并 声明 DispatcherServlet。 


实际 上 ， 要 将 Spring Boot 应 用 构建 为 WAR 文 件 并 不 困难 。 在 使 用 
Initializr 创 建 应 用 的 时 候 ， 如 果 选 择 了 WAR 方 采 ， 其 实 并 没有 额外 要 做 
的 事情 了 。 


Initializr 会 确保 所 生成 的 项 目 包 含 servlet initializer 类 ， 并 且 构 建文 件 
调整 为 生成 WAR 文 件 。 如 果 你 在 Initializr 中 选择 了 构建 为 JAR 文 件 (或 


者 只 古 轧 知道 它们 之 则 的 兰 卉 是 什么 ) ， 那 么 可 以 继续 癌 下 阅读 。 


首先 ， 我 们 需要 有 一 种 配置 Spring DispatcherServlet 的 方式 。 虽 然 可 
以 通过 web.xml 文 件 来 实现 ， 但 Wi Boot 的 
SpringBootServletInitializer 使 这 个 过 程 变 得 更 加 人 简单 了 。 
SpringBootServletInitializer 十 一 个 能 够 感知 Spring Boot 环 境 的 特殊 
an 。 除 了 配置 Spring 的 DispatcherServlet 
之 外 ，SpringBootServletInitializer 还 会 得 找 Spring 应 用 上 下 文中 所 有 
Filter、 nn 型 的 bean， 并 将 它们 绑 定 到 


Fz DD 


servlet 容 器 中 。 


要 使 用 SpringBootServletInitializer， 我 们 需要 创建 一 个 子 类 并 重 写 
configure() 方 法 来 指明 Spring 配 置 类 。 程 序 清单 19.1 展 现 了 
IngredientServiceServletInitializer， 它 是 SpringBootServletInitializer 的 子 


类 ， 我 们 将 会 使 用 它 来 实现 配料 服务 应 用 。 
程序 清单 19.1 通过 Java 启 用 Spring Web 应 用 


package tacos.ingredients; 


import org.springframework.boot.builder.SpringApplicationBuilder.; 
Import org.springframework.boot.context.web.SpringBootServletInitializer:; 


public class IngredientServiceServletIinitializer 
extends SpringBootServletInitializer { 
QOverride 
protected SpringApplicationBuilder configure( 
SpringApplicationBuilder builder) { 
return builder.sources(IngredientServiceApplication.class); 

} 

} 





我 们 可 以 看 到 ，configure() 方 法 以 参数 形式 得 到 了 一 个 
SpringApplicationBuilder 对 象 ， 并 且 将 其 作为 结果 返回 。 在 中 间 的 代码 
中 ， 它 调用 Sources() 方 法 来 注册 Spring 配置 类 。 在 本 例 中 ， 它 注册 了 
IngredientServiceApplication 类 ， 这 个 类 同时 作为 (可 执行 JAR 的 〉 引导 
类 和 Spring 配 置 类 。 

昌 然 配料 服务 应 用 还 有 其 他 的 Spring 配置 类 ， 但 是 我 们 没有 必要 将 
它们 全 部 注册 到 sources() 方 法 中 。IngredientServiceApplication 类 使 用 了 
@SpringBootApplication， 说 明 将 会 后 用 组 件 扫 摘 。 组 件 扫 朱 功能 会 发 
更 其 他 的 配置 闪 并 将 它们 浓 加 进来 。 

在 大 多 数 情况 下 ，SpringBootServletInitializer 的 子 类 都 是 样板 式 
的 。 它 引用 了 应 用 的 主 配置 类 。 除 此 之 外 ， 在 构建 WAR 时 ， 每 个 应 用 
部 和 是 相同 的 。 我 们 几乎 没有 必要 去 修改 它 。 

现在 ， 我 们 已 经 编写 完 servlet initializer 类 。 接 下 来 ， 必 须要 对 项 目 
的 构建 文件 做 一 些 修改 。 如 果 使 用 Maven 进 行 构 建 ， 那 么 所 需 的 变更 非 
第 徐 单 ， 只 需要 确保 pom.xml 中 的 <packaging> 元 北 设置 成 war 即 可 : 


<packaging>war</packaging> 


Gradle 构 建 所 需 的 变更 也 很 简单 直接 ， 我 们 需要 在 build.gradle 文 件 
中 应 用 war 岳 件 : 


apply plugin: “war 


现在 ， 我 们 融 可 以 构建 应 用 了 。 如 条 便 用 Maven， 那 么 我 们 可 以 信 


助 Initializr 所 使 用 的 Maven 包 装 磊 来 执行 package goal: 


$ mvnw package 


构建 成 功 的 话 ，WAR 文 件 将 会 出 现在 target 目 录 下 。 如 果 使 用 
Gradle 来 构建 项 目 ， 那 么 可 以 使 用 Gradle 包 装 需 来 执行 build 任 务 : 


$ gradlew build 


构建 完成 之 后 ， 我 们 可 以 在 build/libs 目 录 下 找到 WAR 文 件 。 剩 下 的 
事情 就 是 部 团 应 用 了 。 不 同 应 用 服务 占有 的 部 区 过 程 会 有 所 差异 ， 所 以 请 
参考 应 用 服务 右 部 区 过 程 的 相关 文档 。 


比较 有 意思 的 事情 是 ， 虽 然 我们 构建 了 适用 于 Servlet 3.0〈 或 更 高 
版 本 ) 部 署 的 WAR 文 件 ， 但 是 这 个 WAR 文 件 依 然 可 以 像 可 执行 JAR 文 
件 那 样 在 命令 行 中 执行 : 


实际 上 ， 使 用 一 个 部 署 制 件 ， 我 们 同时 实现 了 两 种 部 署 方 采 。 
将 做 服 务 放 到 应 用 服务 部 中 


按照 我 们 的 初 袁 ， 更 大 的 Taco Cloud 应 用 是 由 多 个 微服 务 应 用 组 成 
的 ， 而 配料 服务 只 是 其 中 之 一 。 但 是 ， 在 这 里 ， 我 们 所 讨论 的 是 将 配料 
服务 部 署 为 一 个 单独 的 应 用 ， 并 将 其 放 到 应 用 服务 需 中 。 这 样 做 是 合理 
的 吗 ? 


人 向 服 务 通 钊 和 其 他 的 应 用 一 样 ， 应 该 可 以 独立 部 普 。 尽 管 离开 了 
Taco Cloud 应 用 的 上 下 文 之 后 ， 配 料 服 务 也 没有 太 大 的 用 处 ， 但 是 没有 
理由 不 能 将 其 部 闭 到 Tomcat 或 其 他 应 用 服务 夯 中 。 不 过 ， 我 们 需要 注意 
的 是 ， 不 要 期 户 它 能 够 具有 像 部 闭 到 云 中 那样 的 可 扩展 性 。 


虽然 WAR 文 件 作为 Java 部 普 的 主流 方案 已 丝 有 20 多 年 的 历史 了 ， 但 
是 它们 确实 是 为 将 应 用 程序 部 粥 到 传统 Java 应 用 服务 右 而 设计 的 。 按 照 
我 们 所 选 撞 的 平台 ， 现 代 云 部 普 方 案 并 个 需要 WAR 文 件 ， 有 些 其 全 者 
不 支持 这 种 格式 。 随 看 我 们 进入 云 部 闭 的 新 时 代 ，JAR 文 件 可 能 是 更 好 
的 选择 。 


19.3 ” 推 达 JAR 文 件 到 Cloud Foundry 上 


服务 硕 的 便 件 购买 和 维护 成 本 可 能 代价 部 郧 。 当 出 现 高 负载 时 ， 恰 
当地 对 服务 硕 进 行 扩展 是 非 钊 困难 的 ， 对 有 些 组 织 来 说 ， 这 样 做 长 至 是 
不 允许 的 。 如 今 ， 相 对 于 在 目 己 的 数据 中 心 运行 应 用 ， 将 应 用 部 普 到 云 
中 和 是 一 种 人 们 广 沁 关注 并 且 能 够 节省 成 本 的 方案 。 


我 们 有 多 种 可 选 的 云 方案 ， 但 是 人 们 目前 最 关注 的 是 平台 即 服 务 
(Platform as a Service，PaaS) 。PaaS 所 供 了 现成 的 应 用 部 著 平 台 ， 其 
中 包含 多 种 可 以 绑 定 到 应 用 上 的 附加 服务 (比如 数据 库 和 消 奶 代理 ) 。 
除 此 之 外 ， 如 果 你 的 应 用 需要 后 外 的 处 理 能 力 ， 那 么 云 平台 很 容易 在 运 
行 时 对 应 用 进行 扩展 (或 收缩 ) ， 这 是 通过 添加 和 移 除 实例 实现 的 。 


Cloud Foundry 是 一 个 开源 的 PaaS 平 台 ， 起 源 于 Pivotal (Spring 框架 


和 Spring 平 台中 的 其 他 库 也 都 是 由 这 家 公司 赞助 的 ) 。Cloud Foundry 最 
令 人 关注 的 一 点 在 于 它 提供 了 开源 和 基于 商业 的 发 行 版 ， 让 我 们 可 以 选 
择 如 何以 及 在 哪里 使 用 Cloud Foundry。 它 甚至 可 以 运行 在 防火 墙 之 内 的 
公司 数据 中 心里 面 ， 提 供 私有 云 方案 。 


虽然 Cloud Foundry 很 乐意 接受 WAR 文 件 ， 但 是 对 于 Cloud Foundry 
的 需要 来 襄 ，WAR 文 件 格 式 过 于 重量 级 了。 更 简单 的 可 执行 JAR 文 件 更 
sa 
口 口 


适合 部 普 到 Cloud Foundry 中 。 


为 了 演示 如 何 构 建 和 部 普 可 执行 JAR 文 件 到 Cloud Foundry， 我 们 将 
会 构建 配料 服务 应 用 并 将 其 部 垩 到 Pivotal Web Services (PWS) 上 。 如 
条 想 要 使 用 PWS， 我 们 融 需 要 注册 一 个 账户 。PWS 提 供 87 天 元 的 免费 试 
用 功能 ， 在 试用 期 间 甚 至 不 需要 提供 任何 信用 卡 信息 。 


注册 完 PWS 之 后 ， 我 们 需要 从 PWS 下 载 并 安装 cf 命令 行 工 具 。 我 们 
将 会 使 用 cf 工具 将 应 用 推送 至 Cloud Foundry。 首 先 ， 我 们 需要 使 用 它 来 
登录 PWS 账 号 : 
$ cf login -a https://api.run.pivotal.io 
API endpoint: https://api.run.pivotal.io 


Email> {your email} 


Password> {your password} 


Authenticating... 
OK 





非常 好 ! 现在 ， 我 们 已 经 准备 好 将 配料 服务 部 著 到 云 中 了 了。 实际 
上 上 ， 这 个 项 目 本 和 刁 现 在 就 可 以 部 普 到 Cloud Foundry 中 ， 我 们 所 需要 做 的 


束 古 构建 并 将 其 推 运 全 云 病 。 
要 使 用 Maven 构 建 项 目的 话 ， 我 们 可 以 使 用 Maven 包 装 器 执行 


package goal 〈 将 会 在 target 目 录 下 得 到 形成 的 JAR 文 件 ) : 


$ mvnw package 


如 果 使 用 Gradle， 那 么 我 们 可 以 使 用 Gradle 包 装 器 运行 build 任 务 
(将 会 在 build/Nibs 目 录 下 得 到 形成 的 JAR 文 件 ) : 


$ gradlew build 


现在 ， 和 狮 下 的 事情 就 是 使 用 cf 命令 将 JAR 文 件 推送 全 Cloud 
Foundry: 


$ cf push ingredient-service -p target/ingredient-service-6.0.19-SNAPSHOT . 


Jar 





cf push 命 令 的 第 一 个 参数 指定 了 在 Cloud Foundry 中 该 应 用 的 名 称 。 
除了 其 他 蕊 能 之 外 ， 这 个 名 称 还 会 用 作 应 用 托管 的 和 子 域 。 因 此 ， 非 种 重 
要 的 一 点 在 于 ， 我 们 为 应 用 设置 的 名 称 必 须 是 唯一 的 ， 避 免 与 Cloud 
Foundry 己 部 著 的 应 用 (包括 其 他 Cloud Foundry 用 户 所 部 普 的 应 用 ) 冲 


ee 
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想 一 个 唯一 名 称 可 能 会 比较 麻烦 ，df push 命 令 提 供 了 --random-route 
选项 ， 它 会 为 我 们 随机 生成 一 个 子 域 。 如 下 的 命令 展现 了 如 何 将 配料 服 
务 应 用 推送 至 一 个 随机 生成 的 路 由 : 


E cf push ingredient-service \ | 


-p target/ingredient-service-0.0.19-SNAPSHOT.Jar \ 
--random-route 





在 使 用 --random-route 的 时 候 ， 依 然 需要 应 用 名 称 ， 但 是 会 在 该 名 称 
上 拼接 两 个 随机 选 撞 的 单词 以 生成 子 域 。 


假设 所 有 的 过 程 部 很 顺利 ， 应 用 应 该 已 经 部 音 束 位 并 且 可 以 处 理 请 
求 了 ， 了 于 域 是 mgredient-service， 那 么 我 们 可 以 通过 浏览 右 访 问 
http://ingredient-service.cfapps.io/ingredients 来 查看 实际 效果 。 在 啊 应 
中 ， 我 们 会 看 到 一 个 可 用 配料 的 列表 。 


在 我 编写 该 应 用 的 时 候 ， 它 会 使 用 咀 入 式 的 Mongo 数 据 库 (这样 做 
只 是 为 了 测试 ) 来 存放 配料 数据 。 在 生产 环境 中 ， 我 们 可 能 想 要 使 用 真 
下 的 数据 库 。 在 我 编写 本 书 的 时 候 ，PWS 提 供 了 一 个 完全 托 省 的 
MongoDB 服 务 ， 名 为 mlab 。 我 们 可 以 使 用 cf marketplace 命 令 介 看 该 服务 
(以 及 其 他 所 有 可 用 的 服务 ) 。 要 创建 mlab 实 例 ， 我 们 可 以 使 用 cf 


create-service 命 令 : 


$ cf create-service mlab sandbox ingredientdb 


该 命令 会 按照 沙 箱 (sandbox)〉 服务 计划 创建 一 个 mlab 服 务 ， 名 为 
ingredientdb。 服 务 创 建 完成 之 后 ， 我 们 可 以 使 用 cf bind-service 命 令 将 其 
绑 定 到 应 用 上 。 例 如 ， 要 将 ingredientdb 服 务 绑 定 至 配料 服务 应 用 ， 我 们 
可 以 使 用 如 下 的 命令 : 


$ cf bind-service ingredient-service ingredientdb 


将 服务 绑 定 全 应 用 只 是 为 应 用 捉 供 了 如 何 连接 至 服务 的 详情 ， 这 十 


通过 名 为 VCAP_SERVICES 的 环境 变量 实现 的 。 它 并 没有 改变 应 用 使 用 
服务 的 方式 。 服 务 绑 定 完成 之 后 ， 我 们 需要 重新 部 署 〈re-stage) 应 用 才 
能 使 绑 定 生效 : 


$ cf restage ingredient-service 


cf restage 命 令 会 强制 Cloud Foundry 重 新 部 署 应 用 并 重新 计算 
VCAP SERVICES 的 值 。 在 这 个 过 程 中 ， 它 会 发 现 应 用 绑 定 了 一 个 
MongoDB 服 务 ， 了 驶 会 使 用 访 服 务 作 为 应 用 的 后 闯 数 据 库 。 


PWS 提 供 了 很 多 可 用 的 服务 ， 我 们 可 以 直接 将 它们 绑 定 到 应 用 中 ， 
包括 MySQL 数 据 库 、PostgreSQL 数 据 库 ， 甚 全 现成 的 Eureka 和 Config 
Server 服 务 。 建 议 你 阅读 一 下 PWS 的 Marketplace 页 面 ， 以 了 解 PWS 都 提 
供 了 哪些 服务 。 关 于 PWS 如 何 使 用 ， 可 以 参考 其 官网 。 


对 于 Spring Boot 应 用 的 部 葡 来 计 ，Cloud Foundry 是 一 个 非常 棒 的 
PaaS 方 采 。 和 鉴于 它 与 Spring 项 目 之 则 的 关系， 所 以 会 在 这 两 者 之 间 提 供 
一 些 协 同 的 功能 。 在 云 中 部 普 应 用 程序 的 另 一 种 第 见方 法 是 将 应 用 程序 
打包 人 到 Docker 容 如 中 ， 然 后 发 布 到 云 中 ， 在 将 应 用 程序 推进 到 AWS 这 样 
的 基础 设施 即 服 务 (Infrastructure-as-a-Service, IAAS) 平台 时 更 是 如 
此 。 下 和 面 让 我 们 看 看 如 何 创 建 一 个 携 市 Spring Boot 必 用 程序 的 Docker 容 


记忆 


耳闻 。 
19.4 在 Docker 容 器 中 运行 Spring Boot 


在 分 发 云 中 部 署 的 各 种 应 用 时 ，Docker 已 经 成 为 事实 标准 。 很 多 云 


环境 都 接受 以 Docker 容 堪 的 形式 部 闭 应 用 ， 包 括 AWS、Microsoft 
Azure、Google Cloud Platform 和 Pivotal Web Services〈 傈 单 举 例 ) 。 


容 姻 化 应 用 程序 (比如 使 用 Docker 创 建 的 应 用 程序 ) 的 概念 借鉴 了 
现实 世界 中 的 联运 集装箱 。 在 运输 过 程 中 ， 不 官 里 面 的 东西 是 什么 ， 所 
有 的 联运 集 竣 箱 都 有 一 个 标准 的 乒 寸 和 格式 。 正 因为 如 此 ， 联 运 集 斤 箱 
才能 够 很 容易 地 堆放 在 船上 、 火 车 上 或 卡车 上 。 按 照 类 似 的 方式 ， 容 右 
化 的 应 用 程序 于 循 通用 的 容 套 格式 ， 可 以 在 任何 地 方 部 普 和 运行 ， 而 不 
必 天 心里 面 的 应 用 是 什么 。 


尽管 创建 Docker 镜 像 并 不 困难 ， 但 是 Spotify 提 供 了 一 个 Maven 邱 
件 ， 借 助 它 我 们 可 以 轻而易举 地 将 Spring Boot 的 构建 结果 创建 为 Docker 
容 颈 。 要 使 用 该 Docker 捕 件 ， 需 要 将 其 添加 到 Spring Boot 项 目 pom.xml 
文件 的 <build>/<plugins> 代 码 块 下 : 


<build> 
<plugins> 


<plugin> 
<groupId>com.spotify</groupId> 
<artifactId>dockerfile-maven-plugin</artifactId> 
<version>1.4.3</version> 
<configuration> 
<repository> 
${docker.image.prefix}/${project.artifactId} 
</repository> 
<buildArgs> 
<JAR_ FILE>target/${project.build.finalName}.jar</JAR FILE> 
</buildArgs> 
</configuration> 
</plugin> 
</plugins> 
</build> 





在 <configuration> 代 码 氛 下 ， 我 们 设置 了 一 些 属性 ， 用 于 指导 如 何 
创建 Docker 镜 像 。<repository> 摘 述 了 在 Docker 仓 库 中 该 Docker 镜 像 的 名 
称 。 按 照 这 里 的 设置 ， 其 名 称 是 Maven 项 目的 artifact ID， 加 上 Maven 属 
性 docker.image.prefix 的 值 作为 前 级 。 项 目的 artifact ID 是 Maven 已 知 的 ， 
而 前 缀 属性 则 需要 我 们 进行 设置 : 


<properties> 


<docker.image.prefix>tacocloud</docker.image.prefix> 
</properties> 





以 Taco Cloud 的 配料 服务 来 讲 ， 所 形成 的 Docker 锐 像 在 Docker 仓 库 
的 名 称 为 tacocloud/ingredient-service。 


在 <buildArgs> 元 系 下 面 ， 我 们 声明 镜像 要 包含 Maven 构 建 所 生成 的 
JAR 文 件 ， 在 这 里 使 用 Maven 属 性 project.build.finalName 来 确定 target 目 
录 下 JAR 文 件 的 名 称 。 


除了 提供 给 Maven 构 建文 件 的 信息 之 外 ，Docker 镜 像 的 所 有 定义 都 
位 于 一 个 名 叫 Dockerfile 的 文件 中 。 这 个 文件 指明 了 新 镜像 要 基于 哪个 
基础 镜像 、 要 设置 的 环境 变量 、 要 mount 的 郑 以 及 了 最 重要 的 入 口 点 

(entry point) 。 入 口 点 也 就 是 基于 该 锐 像 的 容器 在 局 动 时 要 执行 的 命 
令 。 对 于 大 多 数 Spring Boot 应 用 来 讲 ， 如 下 的 Dockerfile 束 是 一 个 很 好 的 
起 点 : 





FROM openjdk:8-jdk-alpine 

ENV SPRING PROFILES ACTIVE docker 
VOLUME /tmp 

ARG JAR FILE 

COPY ${JAR FILE} app.jar 


ENTRYPOINT ["java",\ 
"-Djava.security.egd=file:/dev/./urandom",\ 
"-jar",\ 
"/app.jar"| 





我 们 将 Docker 文 件 逐 行 拆 分 ， 将 会 看 到 它 包 含 如 下 内 容 。 


。 FROM 指令 声明 了 新 镜像 要 基于 哪个 基础 镜像 。 新 的 镜像 会 扩展 基 
俩 镜 像 。 在 本 例 中 ， 基 础 镜像 为 openjdk:8-jdk- alpine， 这 古 一 个 基 
于 OpenJDK 8 的 容 絮 镜像。 

ENV 指 令 设 置 了 环境 变量 。 我 们 可 以 基于 激活 状态 的 profile 重 写 一 
些 Spring Boot 悄 用 的 配置 属性 ， 所 以 在 本 镜像 中 ， 我 们 将 
SPRING_PROFILES_ACTIVE 坏 境 变 量 设置 为 docker， 从 而 确保 
Spring Boot 应 用 局 动 时 docker 是 处 于 激活 状态 的 profile。 

。 VOLUME 指 令 在 容器 中 创建 了 一 个 mount 态 。 在 本 例 中 ， 它 

在 “tmp” 创 建 了 一 个 mount 点 ， 所 以 需要 的 话 可 以 将 数据 与 

入 “/tmp” 目 了 下 。 

ARG 指 令 声明 了 一 个 要 在 构建 期 传 入 的 参数 。 在 本 例 中 ， 它 声明 了 
名 为 JAR_FILE 的 参数 ， 与 Maven 插 件 <buildArgs> 代 但 块 中 的 参数 
征 相 同 的 。 

COPY 指 令 会 将 给 定 路 径 下 的 未 个 文件 复制 到 另外 一 个 路 径 下 。 在 
本 例 中 ， 它 会 将 Maven 搬 件 中 声明 的 JAR 文 件 复制 为 容 问 中 名 为 
app.jar 的 文件 。 

ENTRYPOINT 摘 述 了 容 句 局 动 的 时 候 要 执行 什么 操作 。 它 以 数组 
的 形式 指定 了 要 执行 的 命令 行 。 在 本 例 中 ， 它 使 用 java 命 令 来 运行 
可 执行 的 app.jar。 


我 们 独 重 介绍 一 下 ENV 指 令 。 在 任何 包含 Spring Boot 应 用 程序 的 容 
器 镜像 中 设置 SPRING PROFILES _ ACTIVE 环境 变量 通常 都 是 一 个 好 办 
法 。 这 样 的 话 ， 我 们 可 以 配置 一 些 仪 在 Docker 下 运行 应 用 时 有 效 的 bean 


和 配置 属性 。 


对 于 配料 服务 ， 我 们 需要 将 应 用 程序 链接 到 运行 在 单独 容 右 中 的 
Mongo 数 据 库 。 默 认 情 况 下 ，Spring Data 会 答 试 连接 localhost 上 监听 端 
口 27017 的 Mongo 数 据 库 。 但 是 ， 这 种 做 法 只 有 在 本 地 运行 的 时 候 才 有 
效 ， 并 不 适合 容 葵 。 因 此 ， 我 们 需要 配置 spring.data.mongodb.host 属 
性 ， 告 诉 Spring Data 要 访问 哪个 主机 上 的 Mongo。 


虽然 我 们 可 能 还 不 知道 Mongo 数 据 库 运 行 在 何 处 ， 但 是 我 们 可 以 通 
过 application.yml 文 件 配 置 Docker 特 定 的 配置 ， 让 它 在 docker profile 处 于 
激活 状态 时 配置 Spring Data 连 接 名 为 mongo 的 主机 上 的 Mongo: 


Spring : 
profiles: docker 


data: 
mongodb: 
host: mongo 





随后 ， 当 我 们 局 动 Docker 容 霹 的 时 候 ， 会 将 mongo 主 机 映射 到 一 个 
在 不 同 容 右 中 运行 的 Mongo 数 据 库 上 。 现 在 ， 我 们 驳 来 构建 容 规 镜像 。 
借助 Maven 包 装 嚣 ， 执 行 pDackage 和 dockerfile:build goal 来 构建 JAR 文 件 ， 
然后 构建 Docker 镜 像 : 


此 时 ， 我 们 可 以 通过 docker images 来 校 验 本 地 镜像 仓库 中 的 镜像 
(为 了 可 读 性 和 适应 本 书 的 宽度 ， 这 里 将 CREATED 和 SIZE 列 删 减 掉 
了 了) : 


$ docker images 
REPOSITORY TAG IMAGE ID 
tacocloud/ingredient-service latest 7e8ed26e768e 


在 启动 容器 之 前 ， 我 们 需要 启动 Mongo 数 据 库 的 容器 。 如 下 的 命令 
显示 了 运行 一 个 名 为 tacocdloud-mongo 的 狐 容 右 ， 其 中 包含 Mongo 3.7.9 数 


扰 库 : 


$ docker run --name tacocloud-mongo -d mongo:3.7.9-xenial 


现在 ， 我 们 终于 可 以 运行 配料 服务 容 如 了 ， 并 链接 它 到 刚刚 局 动 的 


a DD 


Mongo 容 右上 : 


$ docker run -p 806806:80681 \ 
--link tacocloud-mongo:mongo \ 


tacocloud/ingredient-service 





这 里 的 docker run 命 令 有 多 个 值得 介绍 的 重要 组 件 。 


。 因为 我 们 配置 了 容器 中 的 Spring Boot 必 用 运行 在 8081 端 口上 ， 所 以 - 
p 参 数 可 以 将 内 部 端口 映射 到 主机 的 8080 端 口上 。 

。 --link 人 参数 能 够 将 我 们 的 容 吉 名 链接 到 兴 为 tacocloud-mongo 的 容 佛 
上 ， 并 为 其 分 配 mongo 主 机 名 ， 这 样 Spring Data 束 可 以 使 用 该 主 机 
名 连接 它 了 。 

。 最 后 ， 我 们 指定 了 容器 要 运行 的 镜像 名 称 〈 也 残 是 


tacocloud/ingredient-service ) 。 


现在 ，Docker 镜 像 构建 完成 并 且 已 经 证 明 可 以 作为 本 地 容器 运行 
我 们 可 以 更 进一步 ， 将 镜像 推送 至 Dockerhub 或 其 他 Docker 镜 像 仓 库 。 
如 果 你 有 Dockerhub 账 号 并 且 已 经 登录 ， 那 么 可 以 使 用 如 下 的 Maven 命 


令 推 达 镜 像 : 


$ mvnw dockerfile:push 


这 样 的 话 ， 我 们 可 以 将 镜像 部 普 到 几乎 所 有 文 持 Docker 容 需 的 环境 
中 ， 包 括 AWS、Microsoft Azure 和 Google Cloud Platform。 你 可 以 选择 
任意 的 环境 并 投 照 平台 相关 的 指令 部 普 Docker 镜 像 。 


19.5 ”以 终 为 始 


在 过 去 的 几 百 页 中 ， 我 们 从 一 个 徐 单 的 起 点 开始 《〈 更 具体 来 讲 ， 也 
残 定 start.spring.io) ， 最 终 将 应 用 部 署 到 了 云 中 。 我 布 望 在 这 几 百 页 
中 ， 你 所 能 获取 到 的 乐趣 与 我 在 编写 本 书 的 过 程 中 是 一 样 的 。 


虽然 本 书 必 须要 结束 了 ， 但 是 你 的 Spring 征 程 才刚 刚 开 始 。 利 用 本 
书 所 党 的 知识 ， 用 Spring 构 建 令 人 赞叹 的 应 用 吧 ! 我 迫 不 及 竺 地力 知 道 
你 们 的 成 融 。 


19.6 ”小结 


。 Spring 应 用 可 以 部 奢 到 多 种 不 同 的 环境 中 ， 包 括 传统 的 应 用 服务 
左 、 像 Cloud Foundry 这 样 的 平台 即 服务 环境 ， 或 者 Docker 容 喜 。 

。 在 构建 WAR 文 件 的 时 候 ， 我 们 应 当 包 含 一 个 
SpringBootServletInitializr 的 子 类 ， 人 确保 Spring 的 DispatcherServlet 恰 
当地 进行 了 配置 。 

。 构建 可 运行 的 JAR 文 件 人 允许 将 Spring Boot 应 用 部 署 到 多 个 云 平台 
上 ， 而 且 能 够 避免 WAR 文 件 市 来 的 开销 。 


。 信 助 Spotify 的 Maven Dockerfile 捕 件 ， 能 够 非 间 容易 地 容器 化 Spring 
应 用 。 它 会 在 Docker 容 器 中 包装 一 个 可 执行 的 JAR 文 件 ， 容 器 可 以 
部 普 到 任何 文 持 Docker 的 环境 中 ， 其 中 包括 像 Amazon Web 
Services、 Microsoft Azure、Google Cloud Platform、Pivotal Web 
Services (PWS) 、Pivotal Container Service (PKS) 这 样 的 云 供应 


附录 ”初始 化 Spring 应 用 


有 很 多 种 方式 都 可 以 初始 化 Spring 项 目 ， 人 至 于 选择 哪 一 种 完全 取决 
于 个 人 豆 好 。 其 中 ， 很 多 方案 是 由 我 们 豆 欢 哪 蒜 IDE 决 定 的 。 

我 们 在 这 里 所 讨论 的 可 选 方案 除了 一 种 之 外 ， 其 他 的 都 是 基于 
Spring InitializrHJ，Spring Initializr 是 一 个 能 够 为 我 们 生成 Spring Boot 项 
目的 REST API。 各 种 IDE 只 不 过 是 REST API 的 客户 端 。 另 外 ， 还 有 几 
种 方式 可 以 在 IDE 之 外 使 用 Spring Initializr API。 


在 本 附录 中 ， 我 们 将 会 快速 看 一 下 所 有 的 可 选 方案 。 
A.1 使 用 Spring Tool Suite 初 始 化 项 目 


要 使 用 Spring Tool Suite 来 初始 化 新 的 Spring 项 目 ， 我 们 需要 在 File > 
New 有 闻 单 中 选择 Spring Starter Project 亲 单项 ， 如 图 A.1 所 示 。 


名” Spring Tool Suite | File Edit Source Refactor Navigate Search Project Run Window Help 
@@@ A ~%N bP 曼 Spring Starter Project 
mir 芍 " Or OB， pen Flle... (Imnort Snoring Gettina Started Content 





图 A.1 在 Spring Tool Suite 中 初始 化 一 个 新 项 目 


注意 : 这 是 一 个 使 用 Spring Tool Suite 初 始 化 Spring 项 目的 徐 


单 描述 。 更 详细 的 前 述 ， 可 以 参考 1.2.1 小 节 。 





接 下 来 ， 我 们 将 会 看 到 项 目 创建 对 话 框 的 第 一 页 〈 见 图 A.2) 。 在 
这 个 页 面 中 ， 我 们 将 会 定义 项 目的 基本 信息 ， 比 如 项 目 名 称 、 坐 标 
(group ID 和 artifact ID ) 、 版 本 和 基础 包 名 。 我 们 也 可 以 确定 项 目 使 用 
Maven 还 是 Gradle 来 构建 ， 还 可 以 声明 构建 生成 JAR 文 件 还 是 WAR 文 
件 ， 以 及 使 用 哪个 版 本 的 Java， 甚 至 还 能 使 用 其 他 的 JVM 语 言 ， 比 如 
Groovy 或 Kotlin。 


New Spring Starter Project 





Service URL http://start.spring.io 
Name taco-cloud 


Use default location 


Location 

Type: Maven Packaging: Jar 
Java Version: 1.8 Language: Java 
Group sia 

Artifact taco-cloud 

Version 0.0.1-SNAPSHOT 

Description Taco Cloud Example 

Package tacos 


Working sets 


Add project to working sets New... 


Working sets: 


@ Next > Cancel 





图 A.2 定义 基本 的 项 目 信 息 


这 个 页 面 的 第 一 个 输入 域 要 求 我 们 指定 Spring Initializr 服 务 的 位 


置 。 如 果 你 运行 或 使 用 自 定义 的 Pnitializr 实 例 ， 那 么 可 以 在 这 里 指定 
Initializr 服 务 的 基础 URL; 售 则 ， 使 用 默认 的 http:/start.spring.io 残 可 以 
下 


在 定义 完 项 目的 基本 信息 之 后 ， 点 击 Next 按 钮 ， 会 看 到 项 目的 依赖 
页 《 见 图 A.3) 。 


New Spring Starter Project Dependencies (0) 


Spring Boot Version: 2.0.0 M2 





Available: Selected: 


[ Typetosearch dependencies | X DevTiools 


Lombok 
Thymeleaf 
Web 





b Cloud AWS 2 
» Cloud Circuit Breaker X 
b Cloud Config 
b Cloud Contract 
b Cloud Core 
b Cloud Discovery 
b Cloud Messaging 
b Cloud Routing 
b Cloud Tracing 
b Core 
» 1/O 
b NoSQL 
bp Ops 
b Pivotal Cloud Foundry 

b SQL 

b Social 

b Template Engines 
v Web 

园 Web 

Reactive Web 


Websocket 
A Make Default Clear Selection 


(2) < Back Next > Cancel 
图 A.3 指定 项 目的 依赖 


在 项 目 依 赖 页 中 ， 我 们 可 以 指定 项 目 害 要 的 所 有 依赖 。 其 中 ， 有 有 些 


依赖 是 Spring Boot Starter 依 赖 ， 有 些 依赖 是 Spring 项 目 第 用 的 依赖 。 


可 用 的 依赖 部 列 在 左 侧 ， 以 分 组 的 形式 进行 组 织 ， 可 以 展开 和 路 
因 。 如 朵 在 俘 找 依赖 时 过 到 有 拷 烦 ， 还 可 以 对 依赖 进行 搜索 ， 以 便于 铁 小 
可 选 施 围 。 


要 将 菜 个 依赖 洪 加 到 所 生成 的 项 目 中 ， 我 们 只 需要 选中 依赖 名 称 前 
面 的 复 选 征 即 可 。 已 经 选中 的 依赖 会 显示 在 右 侧 Selected 标 题 下 面 。 如 
末 想 要 移 除 依 顿 ， 可 以 点 击 已 选中 依 顿 前面 的 x， 也 可 以 点 击 Clear 
Selection 按 钮 清除 所 有 已 选 的 依赖 。 


为 了 增加 便利 性 ， 如 果 你 发 现在 项 目 中 特定 的 一 组 依赖 始终 (或 者 
经 常 ) 会 用 到 ， 那 么 你 可 以 在 选择 完 这 些 依赖 后 点 击 Make Default 按 
钮 ， 这 样 在 下 一 次 创建 项 目的 时 候 它 们 会 预先 选中 。 


在 选择 完 之 后 ， 扩 击 Finish 按 钮 束 可 以 生成 项 目 并 添加 到 工作 空间 
中 了 。 


如 果 你 想 要 使 用 http://start.spring.io 之 外 的 其 他 Initializr， 可 以 点 击 
Next 按 钮 来 设置 Initializr 的 基础 URL， 如 图 A.4 所 示 。 


New Spring Starter Project 


© 


Site Info 


Base Url “http://start.spring.io/starter.zip 


Full Url http://start.spring.io/starter.zip?name=taco- 


cloud&groupld=sia&artifactld=taco-cloud&version=0.0.1- 


SNAPSHOT&description=Taco+Cloud+Example&packageName=tacos&t 
ype=maven- 


project&packaging=jar&javaVersion=1.8&language=java&bootVersion=2 


(2) < Back 


Cancel Finish 


图 A.4 指定 Initializr 的 基础 URL 


Base Url 输入 域 指 定 了 Initializr API 监 听 的 URL。 在 这 个 页 面 中 ， 这 
征 唯 一 可 以 修改 的 输入 域 。Full Un 输入 域 展 现 了 通过 Initializr 请 求 新 项 
目的 完整 UREL 地 址 。 


A.2 使 用 IntelliJ IDEA 初 始 化 项 目 


如 果 要 使 用 IntelliJ IDEA 初 始 化 Spring 项 目 ， 就 在 File > New 荣 单 下 
选择 Project 腔 单项 ， 如 图 A.5 所 示 。 


摆 ”IntelliJ IDEA | File | Edit View Navigate Code Analyze Refactor Build Run To 
DI 


Oe@e New Project... 
号 TacoCloud ) 二 Open.… Proiect from Existina Sources... 





图 A.5 在 IntelliJj IDEA 中 初始 化 一 个 新 的 Spring 项 目 


此 时 ， 将 会 打开 新 Spring Initializr 项 目 向 导 的 第 一 页 (参见 图 
A.6) 。 在 本 页 中 ， 通 党 我 们 会 直接 点 击 Next 按 钮 进入 下 一 页 。 如 果 你 
想 要 使 用 与 https://start.spring.io 个 同 的 Spring Initializr， 束 可 以 选中 
Custom 音 选 枉 ， 并 输入 想 要 使 用 的 Spring Initializr 的 基础 URL。 


@°® New Project 
站 Java Project SDK: 卡 java version "1.8.0_121" (/Library/Java/JavaVirtualMachines/jdk1.8.0 1 接 New... 
村 Java Enterprise 
Choose Initializr Service URL. 
%。JBoss 
网 J2ME © Default: https://start.spring.io 
国 clouds Custom: 
pring Make sure your network connection is active before continuing. 
Java FX 
嘱 ' Android 


IntelliJ Platform Plugin 





Spring Initializr 


站 Maven 
(S$ Gradle 


加 Groovy 
© Griffon 
© Grails 


© Application Forge 


国 Static Web 
Cx Flash 


医 Kotlin 


站 Empty Project 


图 A.6 选择 Spring Initializr 的 位 置 


太 击 Next 按 钮 之 后 ， 我 们 将 会 看 到 一 个 输入 项 目 基 本 信息 的 页面 ， 
如 图 A.7 所 示 。 你 会 肥 现 ， 这 个 页 面 上 有 很 多 输入 域 与 Maven pom.xml 中 
的 信息 是 一 臻 的。 实际 上 ， 在 Type 输 入 域 中 选择 Maven Project， 驳 能 友 
现 这 些 输入 域 的 用 途 所 在 。 如 末 你 更 豆 欢 Gradle， 也 可 以 选择 Gradle 


Project。 


@°® 
Group: 
Artifact: 
Type: 


Packaging: 


Java Version: 


Language: 


Version: 
Name: 
Description: 


Package: 


New Project 
sia 
taco-cloud 
Maven Project (Generate a Maven based project archive) 
Jar 
1.8 加 
Java 
0.0.1-SNAPSHOT 
taco-cloud 
Taco Cloud Example 


tacos 


? Cancel Previous 


在 填写 完 必 要 有 的 项 目 信 息 后 ， 扣 击 Next 按 钮 将 会 展现 项 目 依 赖 页 


( 见 图 A.8) 。 





图 A.7 在 IntelliJ IDEA 中 指明 必要 的 项 目 信 息 


@" "| New Project 


Dependencies Q Spring Boot 1.5.4 Selected Dependencies 
Web AOP DevTools 
Template Engines Atomikos (JTA) Lnnibole 

SQL Bitronix (JTA) 

NoSQL Narayana (JTA) Web 

Cloud Core Cache Web 

Cloud Config DevTools 

Cloud Discovery Configuration Processor Template Engines 
Cloud Routing Validation Thymeleaf 
Cloud Circuit Breaker Session 

Cloud Tracing Retry 

Cloud Messaging Lombok 

Cloud AWS 


Cloud Cluster 

Cloud Contract 
Pivotal Cloud Foundry 
Social 

11O 

Ops 


? Cancel Previous 
图 A.8 ”选择 项 目 依 赖 
在 最 左 侧 ， 依 赖 是 按照 分 类 来 组 织 的 。 选 中 某 个 分 类 时 ， 这 个 分 类 
) 


对 应 的 可 选项 会 显示 在 中 间 区 域 。 已 经 选中 的 依赖 将 会 (按照 分 类 ) 5 
在 最 右 侧 。 


人 


在 选择 完 依赖 之 后 ， 点 击 Next 按 钮 ， 我 们 将 会 看 到 项 目 癌 导 的 最 后 
一 页 ， 如 图 A.9 所 示 。 在 这 个 页 面 中 ， 我 们 要 输入 项 目的 名 称 并 指定 项 
目 要 放 到 磁盘 的 什么 位 置 。 


和 国 New Project 
Project name: TacoCloud 


Project location: ~/ldeaProjects/TacoCloud 


» More Settings 


图 A.9 ”设置 项 目的 名 称 和 位 置 


点 击 Finish 按 钮 ， 项 目 将 会 创建 并 加 和 载 到 IntelliJj IDEA 的 工作 空间 
中 。 


A.3 使 用 NetBeans 初 始 化 项 目 


要 使 用 NetBeans 创 建 攻 项目， 上 自 完 要 选择 File 采 早 的 New Project 深 
单项 ， 如 图 A.10 所 示 。 


入 NetBeans | File | Edit View Navigate Source 
ese 
:生生 四 PNew File... NI | 

” 国 Open Project... 他 3O 

Ject » 


Close All Projects Bean 
Open File... 
Open Recent File 





Project Groups... 


Import Project 
Export Project 





Page Setup... 





图 A.10 ”使 用 NetBeans 初 始 化 一 个 新 的 Spring 项 目 


此 时 我 们 会 看 到 新 项 目 问 叶 的 第 一 页 ， 如 图 A.11 所 示 。 访 由 面 会 让 
我 们 选择 想 要 创建 什么 类 型 的 项 目 。 


















@° 鲜 New Project 
Steps Choose Project 
1. Choose Project Q 
By i 
Categories: Projects: 
Bl Java 名 Java Application 
MN JavaFX JavaFX Application 
MN Java Web Web Application 
Bl Java EE 大 日 8g Module 
Spring Boot basic project 
大 HTML5 /JavaScript < 
~ Maven Enterprise Application 
Groovy Enterprise Application Client 
MN NetBeans Modules OSGi Bundle 
>» MM Samples @ NetBeans Module 
忆 ， NetBeans Application 
| ma_ POM proi 
Description: 


Maven Spring Boot project created trough the Spring Initializr web service (at 


Help < Back Next> Finish Cancel 


图 A.11 创建 新 的 Spring Boot Initializr 项 目 


对 于 Spring Boot 项 目 来 说 ， 我 们 要 从 左 侧 的 列表 中 选择 Maven， 然 
后 在 右 侧 的 项 目 列表 中 选择 Spring Boot Initializr Project， 然 后 点 击 Next 


按钮 进入 下 一 页 。 


新 项 目 向 导 的 第 二 页 〈 见 图 A.12) 人 允许 我 们 设置 项 目的 基本 信息 ， 
比如 项 目 名 称 、 版 本 以 及 Maven pom.xml 文 件 中 定义 项 目的 其 他 信息 。 








@° © New Project 

Steps Base Properties 

1. Choose Project - 

2. Base Properties Group: Sia 

3. Dependencies 

4. Name and Location Artifact: taco-cloud 
Version: 0.0.1-SNAPSHOT 
Packaging: Jar 
Name: taco-cloud 
Description: Taco Cloud Example 


Package Name: tacos 


Language: Java 


Java Version: 1.8 


Help < Back Next> Finist Cancel 


图 A.12 声明 项 目的 基本 信息 


在 声明 完 项 目的 基本 信息 之 后 ， 点 击 Next 按 钮 进入 新 项 目 癌 导 的 依 
赖 页 ， 参 见 图 A.13。 


New Project 
Steps Dependencies 
1. Choose Project 
2. Base Properties Boot Version: 1.5.4 Filter 
3. Dependencies | - 
4. Name and Location Web ye 从 
Websocket Web Services 
Jersey UAX-RS) Apache CXF JAX-RS) 
Ratpack Vaadin 
Rest Repositories HATEOAS 
Rest Repositories HAL Browser Mobile 
REST Docs Stormpath 
Keycloak 
Template Engines 
Freemarker Velocity 
Groovy Templates Thymeleaf 
< Back Next> nisl Cancel 


图 A.13 ”选择 项 目的 依赖 


依赖 会 控 照 分 类 的 形式 全 部 列 在 同一 个 列表 中 。 如 来 在 便 找 特定 依 
赖 时 过 到 麻烦 ， 可 以 使 用 顶部 的 Filter 文 本 框 限制 列表 中 可 选项 的 数量 。 


在 这 个 页 面 中 ， 还 可 以 指定 想 要 使 用 哪个 Spring Boot 版 本 。 它 默认 
会 设置 为 当前 Spring Boot 的 正式 版 本 。 


在 为 项 目 选 择 完 依赖 之 后 ， 点 击 Next 按 钮 会 显示 新 项 目 同 导 的 最 后 
一 页 ， 如 图 A.14 所 示 。 这 个 页 面 允 许 我 们 声明 项 目的 一 些 评 情 信息 ， 包 
括 项 目的 名 称 以 及 文件 系统 中 的 位 置 (Project Folder 文 本 域 是 只 旋 的 ， 
它 的 值 会 根据 其 他 两 个 文本 域 的 值 衔 生 而 来 ，”。 在 这 里 ， 还 允许 我 们 通 
过 Maven Spring Boot 插 件 运 行 和 调试 项 目 ， 而 不 是 使 用 NetBeans。 我 们 
还 可 以 让 NetBeans 移 除 生 成 项 目 中 的 Maven 包 装 器 。 


New Project 
Steps Name and Location 
l. Choose Project 
2. Base Properties Project Name: TacoCloud 
3. Dependencies 
4 


. Name and Location Project Location: /Users/habuma/NetBeansProjects 


Browse... 
Project Folder: rs/habuma/NetBeansProjects/TacoCloud 
Run/Debug trough Spring Boot maven plugin 
Remove Maven Wrapper 
< Back Finish Cancel 


图 A.14 指明 项 目的 名 称 和 位 置 


在 设置 完 项 目的 所 有 信息 后 ， 点 击 Finish 按 钮 ， 项 目 将 会 创建 并 添 
加 人 到 NetBeans 的 工作 空间 中 。 


A.4 在 start.spring.io 中 初始 化 项 目 


到 目前 为 止 所 描述 的 基于 IDE 的 初始 化 方案 可 能 会 满足 你 的 需求 ， 
但 是 有 时 候 你 可 能 希 要 完全 不 同 的 IDE， 或 者 使 用 简单 的 文本 编 人 


时 口 昌 


革 髓 。 
在 这 种 情况 下 ， 你 依然 可 以 借助 基于 Web 界 和 面 的 Initializr 来 使 用 Spring 


Initializr。 


首先 ， 在 Web 浏 览 器 中 访问 https://start.spring.io。 我 们 将 会 看 到 简单 


版 本 的 Spring Initializr Web 用 户 寞 面 ， 如 图 A.15 所 示 。 


art.spring.io 和 由 口 


SPRING INITIALIZR 


Generate a | vavenPoec + WIth Jam ; and Spring Boot 1s4 





Project Metadata Dependencies 
Artifact coordinates Add Spring Boot Starters and dependencies to Your application 
Group Search for dependencies 
sia 
Artifact Selected Dependencies 


Generate Project ¥ +s 


Don't know what to look for? Want more options? Switch to the full version 


start.spring.io is powered by 





图 A.15 简单 版 本 的 Spring Initializr Web 界 面 


在 简单 版 本 的 Initializr Web 应 用 中 ， 我 们 只 需要 填写 ee 
PD 比如 使 用 Maven 还 是 Gradle 进 行 构 建 、 开 发 项 目 要 使 用 什么 
言 、 基 于 什么 版 本 的 Spring Boot 进 行 构建 以 及 项 目的 Ae 


1D。 


我 们 还 可 以 通过 在 Search for Dependencies 文 本 框 中 输入 搜索 条 件 来 
指明 依赖 。 例 如 ， 如 图 A.16 所 示 ， 我 们 可 以 输入 “web” 来 搜索 市 
有 “web” 关 键 字 的 依赖 。 


总 
半 


Se@ : 田 ] start.spring.io © 由 


SPRINGC INITIALIZR 





Generate a | MavenProject + WIth Ja ; and Spring Boot 1s4 


Project Metadata Dependencies 
Artifact coordinates Add Spring Boot Starters and dependencies to your application 
Group Search for dependencies 

taco-cloud Full-stack web development with Tomcat and Spring MVC 


Rest Repositories 
Exposing Spring Data repositories over REST via spring-data-rest-webmvc 


el Validation 
JSR-303 validation infrastructure (already included with web) 


Don't know what to look for? Want more options? Switch to the full version 
Websocket 
Websocket development with SockJS and STOMP 


Web Services 
Contract-first SOAP service development with Spring Web Services 


More matches, please refine your search 


start.spring,.io is powered by and 


图 A.16 搜索 依赖 


当 看 到 目 己 想 要 的 依赖 时 ， 在 键盘 上 按 Return 键 来 选中 它 ， 它 融会 
还 加 到 选中 依赖 的 列表 中 。 在 图 A.17 中 ，Selected Dependencies 文 本 下 
面 显示 已 经 选中 了 Web、Thymeleaf、DevTools 和 Lombok 依 赖 。 


S@@ 《 EN .start ,Spring.io of 由 器 


SPRING INITIALIZR 


Generate a | vavenPoec + With aa ; and Spring Boot 154 





Project Metadata Dependencies 
Artifact coor dinates Add Spring Boot Starters and dependencies to Your application 
Group Search for dependencies 





Artifact Selected Dependencies 


ee 本 CE 





Generate Project % +a 


Don't know what to look for? Want more options? Switch to the full version 


start.spring.io is powered by 





图 A.17 选择 依赖 


如 果 不 想 要 示 个 已 选中 的 依赖 ， 只 二 要 扣 击 依赖 条 目 右 侧 的 x 就 可 
以 将 其 移 除 。 


完成 之 后 ， 我 们 可 以 点 击 Generate Project 按 钮 〈 也 可 以 使 用 按钮 上 
所 电 示 的 快捷 键 ， 不 同 操作 系统 下 会 有 所 差异 ) ， 让 Initializr 初 始 化 项 
目 并 下 载 为 zip 文 件 。 然 后 ， 我 们 束 可 以 解压 该 文件 并 导入 你 所 选择 的 
IDE 或 文本 编辑 郁 了 。 


如 果 你 希望 更 细 粒 虚 地 控制 项 目 创建 的 过 程 ， 可 以 点 击 Generate 
Project 下 的 Switch to the full version 链 接 ， 这 样 用 户 界 面 会 展现 更 多 的 输 
入 域 和 所 有 可 用 依赖 的 复 选 框 列 表 。 图 A.18 显 示 了 了 Web 界面 完整 版 本 的 


| 


SPRING INITIALIZR 





Generate a | MavenProject + With aa ; and Spring Boot 1s4 


Project Metadata Dependencies 
Artifact coordinates Add Spring Boot Starters and dependencies to your application 
Group Search for dependencies 
Artifact Selected Dependencies 

we oe CEZZ 
Nam 

taco-c loud 
Description 

Taco Cloud E pl 


Package Name 


karocloud 


Packaging 


Jar 


Java Version 


1.8 


Too many options? Switch back to the simple version 





Generate Project 3% + 


Core Web 

Security Web 

Secure your application via spring-security Full-stack web development with Tomcat and Spring MVC 
_ AOP Reactive Web 


图 A.18 ”完整 版 本 的 Initializr 用 户 界 面 (部 分 ) 


完整 版 本 中 的 大 多 数 输入 域 都 衍生 自 Group 和 Artifact 和 输入 域 ， 或 者 
在 简单 版 本 中 已 经 有 了 默认 值 。 完 整 版 本 能 够 让 我 们 重 写 这 些 衍 生 值 / 
默认 值 。 


图 A.18 只 展现 了 完整 版 本 中 可 用 依赖 复 选 框 的 一 部 分 ， 所 以 你 可 能 
南 要 问 下 清 动 很 人 才能 找到 想 要 的 依赖 。 不 过 ， 在 完整 版 本 的 用 户 界 面 
中 ， 搜 索 框 依然 是 可 用 的 。 


A.5 使 用 命令 行 初始 化 项 目 


Spring Initializr 的 IDE 和 基于 浏 硕 需 的 用 户 界 面 可 能 是 初始 化 项 目的 
第 见方 式 。 它 们 都 是 Initializr 应 用 程序 提供 的 REST 服 务 的 客户 闪 。 在 东 
些 特殊 情况 下 例如 ， 在 脚本 化 场景 中 ) ， 我 们 可 能 会 友 现 直接 从 命令 
行使 用 Initializr 服 务 也 很 有 用 。 


我 们 有 两 种 消费 该 API 的 方式 : 


。 使 用 cu 命令 或 者 类 似 的 他 信行 REST 客 已 新) ; 
。 使 用 Spring Boot 的 命令 行 接口 ( 叉 称 为 Spring Boot CLI) 。 


下 面 我 们 看 一 下 这 两 种 方案 ， 移 从 curl 命 令 开始 。 
A.5.1 curl 和 Initializr API 


使 用 curl 初 始 化 Spring 项 目的 最 简单 方式 是 按照 如 下 格 却 消费 该 
APIl: 





%» curl https://start.spring.io/starter.zip -oOo demo.zip 


在 本 例 中 ， 我 们 请 求 了 Initializr 鸭 “/starter.zip” 六 点， 它 将 会 生成 一 
个 Spring 项 目 并 下 载 为 zip 文 件 。 生 成 的 项 目 是 使 用 Maven 构 建 的 ， 并 且 
除了 Spring Boot starter 依 顿 外 并 没有 其 他 的 依赖 ，pom.xml 文 件 中 的 所 有 
项 目 信息 都 是 默认 值 。 


如 果 不 进行 特殊 指定 ， 文 件 名 将 会 是 starter.zip。 在 本 例 中 ，-o 选 项 


将 下 载 的 文件 命名 为 demo.zip。 


对 外 公开 的 Spring Initializr 服 务 器 托管 在 https://start.spring.io 上， 如 
果 你 想 要 使 用 自 定义 Initializr， 那 么 需要 对 应 地 修改 URL。 


除了 默认 值 之 外 ， 我 们 可 能 还 想 要 指定 一 些 详情 信息 和 依赖 。 表 
A.1 列 出 了 消费 Spring Initializr REST 服 务 所 有 可 用 的 参数 (及 其 默认 
值 ) 。 


表 A.1 Initializr API 支 持 的 请 求 参数 


默认 值 


项 目的 group ID， 用 于 Maven 仓 库 对 各 种 制 件 的 
如 织 com.example 


项 目的 artifact ID， 将 会 显示 在 Maven 仓 库 中 
项 目 版 本 0.0.1-SNAPSHOT 





项 目 名 称 ， 同 时 也 会 用 来 确定 应 用 主 类 的 名 称 
name . . demo 
(类 名 会 添加 Application 后 级 ) 


、 Demo project for 
description 项 目的 摘 述 
Spring Boot 
packageName 项 目的 基础 包 名 com.example.demo 





基础 的 Spring Boot 
dependencies 项 目 构 建文 件 所 包含 的 依赖 


starter 


所 生产 项 目的 类 型 ，maven-project 或 gradle- 
type maven-project 
project 


当前 GA 版 本 的 
基于 哪个 Spring Boot 版 本 进行 构建 
Spring Boot 


要 使 用 的 编程 语言 ， 可 以 是 java、groovy 或 
language 

kotlin 
packaging 项 目 应 该 如 何 打包 ， 可 以 古 jar 或 war 


applicationName | 应 用 的 名 称 name 参 数 的 值 


pope eto tam 


我 们 可 以 通过 发 送 请 求 至 基础 Initializr URL 获 取 参 数列 表 和 可 用 依 
赖 项 的 列表 : 


















%» curl https://start.spring.io 


在 这 些 参数 中 ， 我 们 可 能 会 友 现 dependencies 是 最 第 用 的 。 例 如 ， 


我 们 想 要 创建 一 个 使 用 Spring 的 简单 Web 项 目 。 如 下 使 用 curl 的 命令 行将 
会 生成 一 个 包含 web starter 依 赖 的 项 目 zip 包 


%» curl https://start.spring.io/starter.zip \ 


-d dependencies=web \ 
-0 demo.zip 





假设 有 一 个 更 复杂 的 样 例 : 我 们 想 要 开 友 一 个 使 用 Spring Data JPA 
进行 数据 持久 化 的 Web 应 用 程序 ， ha ee 
my-dir 的 目录 下 ， 并 且 我 们 不 仅 想 要 下 载 zip 文 件 ， 还 希望 在 下 载 时 将 项 
上 解压 到 文件 系统 中 。 在 这 种 情况 下 ， 下 面 的 命令 可 以 解决 该 问题 : 


%» curl https://start.spring.io/starter.tgz \ 
-d dependencies=web,data-jJpa \ 


-d type=gradle-project 
-d baseDir=my-dir | tar -xzvf - 





在 这 里 ， 下 载 的 zip 文 件 将 会 以 官 刀 的 方式 传 圳 给 tar 命 令 进行 解 
压 。 


A.5.2 Spring Boot 命 令 行 接口 


Spring Boot CLI 是 另 一 种 初始 化 Spring 应 用 的 方案 。 我 们 能 够 以 多 
种 方式 安装 Spring Boot CLI， 最 简单 的 (也 是 我 最 豆 欢 的 ) 方式 可 能 是 
使 用 SDKMAN: 


%» sdk install springboot 


Spring Boot CLI 安 六 完 成 之 后 ， 我 们 就 可 以 使 用 它 来 生成 项 目 了 。 


使 用 方式 与 curl 非 党 类 似 ， 这 里 我 们 要 使 用 的 命令 是 spring init。 实 际 
上 ， 使 用 Spring Boot CLI 生 成 项 目的 最 简单 方式 为 : 


% Spring init 








这 样 会 生成 一 个 Spring Boot 项 目的 骨架 ， 并 且 会 下 载 成 名 为 
demo.z 让 的 zip 文 件 。 


有 时 我 们 可 能 想 要 指明 一 些 详情 信息 和 依赖 ， 表 A.2 列 出 了 spring 
init 命 令 所 有 可 用 的 参数 。 


项 目的 group ID， 用 于 Maven 仓 库 对 各 种 制 件 的 组 
group-id com.example 
织 
项 目的 artifact ID， 将 会 显示 在 Maven 仓 库 中 


S 


表 A.2 ” spring init 命 令 文 持 的 所 有 请 求 参数 


项 目 版 本 0.0.1-SNAPSHOT 
项 目 名 称 ， 同 时 也 会 用 来 确定 应 用 主 类 的 名 称 〈 类 
name ; demo 
名 会 添加 Application 后 缀 ) 
Demo project for 
description 
Spring Boot 








package- 


项 目的 基础 包 名 com.example.demo 


Name 


. . 基础 的 Spring Boot 
dependencies | 项 目 构 建文 件 所 包含 的 依赖 
starter 
所 生产 项 目的 类 型 ，maven-project 或 gradle-project 


基于 哪个 Java 版 本 进行 构建 


当前 GA 版 本 的 
boot-version | 基于 哪个 Spring Boot 版 本 进行 构建 
Spring Boot 
要 使 用 的 编程 语言 ， 可 以 是 java、groovy 或 kotlin 
packaging “| 项 目 应 该 如 何 打 包 ， 可 以 是 jar 或 war 


通过 使 用 --list 参 数 ， 我 们 可 以 列 出 参数 的 列表 以 及 可 用 依赖 : 

















% Spring init -- 1Sst 


假设 我 们 希望 创建 一 个 基于 Java 1.7 的 Web 应 用 ， 那 么 如 下 使 用 -- 


dependencies 和 --java 命 令 即 可 : 


Spring init --dependencies=web --jJava-version=1.7 





假设 我 们 想 要 创建 一 个 使 用 Spring Data JPA 进 行 数据 持久 化 的 Web 


应 用 程序 ， 并 且 还 希望 使 用 Gradle 构 建 它 ， 而 不 是 使 用 Maven， 那 么 我 
们 可 以 使 用 如 下 的 命令 : 


%» Spring init --dependenclies=web ,jpa --type=gradle-project 





你 可 能 已 经 发 现 ，spring init 的 很 多 参数 与 curl 方 宁 的 参数 相同 或 相 
似 。 也 就 是 说 ，spring init 并 没有 文 持 curl 方 案 中 的 所 有 参数 〈 比 如 
baseDir) ， 而 且 参 数 是 中 划 线 分 割 的 而 不 是 采用 驼峰 命名 《〈 例 如 


package-name 与 packageName) 。 


A.6 使 用 元 低 如 创 建 Spring 旋 用 


态 外 值得 一 提 的 是 ， 有 一 些 基于 Spring 和 Spring Boot 构 建 的 框 染 : 


e (GTralls 。 


e JJHipster。 


这 些 元 框架 (meta-framework) 在 更 高 层级 上 提供 了 快速 开发 
Spring 应 用 的 能 力 ， 同 时 依然 能 够 使 用 Spring 和 Spring Boot 所 提供 的 所 有 
功能 。 


这 些 元 框 染 部 有 目 己 独特 的 开 友 模型 实际 上 ， 它 们 本 号 束 古 框 
染 ， 因 此 在 本 附录 中 简单 地 将 它们 作为 项 目 初 始 化 机 制 有 后 个 公平 。 事 
实 上 ， 每 个 元 框 染 部 值得 写 一 本 书 。 


我 们 不 会 深入 研究 如 何 使 用 这 些 元 框 染 来 初始 化 Spring 项 目 ， 在 这 
里 将 它们 列 出 来 只 是 让 读者 知道 还 有 初始 化 和 开发 Spring 应 用 的 其 他 方 


或 ， 
A.7 构建 和 运行 项 目 

不 管 你 采用 什么 方式 初始 化 项 目 ， 都 可 以 在 命令 行 中 使 用 java -jar 
命令 来 运行 应 用 ; 


% Java -Jar demo.Jar 


即使 不 采用 JAR 文 件 而 使 用 WAR 文 件 来 进行 分 发 ， 这 样 做 也 依然 是 
可 行 的 : 


% Java -Jar demo.war 


我 们 还 可 以 使 用 Spring Boot Maven 或 Gradle 插 件 来 运行 应 用 。 比 
如 ， 项 目 使 用 Maven 构 建 的 话 ， 可 以 这 样 运行 : 





% mvn spring-boot:run 
使 用 Gradle 进 行 构建 的 话 ， 可 以 按照 如 下 方式 运行 项 目 : 
%» gradle bootRun 


不 党 是 采用 Maven 还 是 Gradle， 构 建 工 具 都 会 构建 〈 还 没有 构建 的 
话 ) 并 运行 项 目 。 


